Tanácsadói fejlesztési irányelvek

Ez a szakasz azokat az irányelveket ismerteti, amelyeket érdemes megfontolnia a megfelelő fejlesztés és felhasználói élmény biztosítása érdekében. Néha előfordulhat, hogy alkalmazhatók, és néha nem.

Tervezési irányelvek

A parancsmagok tervezésekor az alábbi irányelveket kell figyelembe venni. 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.

InputObject paraméter (AD01) támogatása

Mivel a Windows PowerShell közvetlenül a Microsoft .NET-keretrendszer objektumaival működik, gyakran elérhető egy .NET-keretrendszerobjektum, amely pontosan megfelel a felhasználó által egy adott művelet végrehajtásához szükséges típusnak. InputObject egy olyan paraméter szabványos neve, amely egy ilyen objektumot bemenetként vesz fel. A Stop-Proc minta parancsmagja például egy folyamat típusú paramétert InputObject határoz meg, amely támogatja a folyamat bemenetét. A felhasználó lekérheti a folyamatobjektumok egy készletét, módosíthatja őket, hogy kijelölje a leállítandó pontos objektumokat, majd közvetlenül a parancsmagnak Stop-Proc adja át őket.

A Force paraméter (AD02) támogatása

Időnként a parancsmagnak meg kell védenie a felhasználót a kért művelet végrehajtásától. Az ilyen parancsmagnak támogatnia kell egy Force paramétert, amely lehetővé teszi a felhasználó számára, hogy felülbírálja ezt a védelmet, ha a felhasználó rendelkezik a művelet végrehajtásához szükséges engedélyekkel.

A Remove-Item parancsmag például általában nem távolít el írásvédett fájlokat. Ez a parancsmag azonban támogatja a Force paramétert, így a felhasználó kényszerítheti egy írásvédett fájl eltávolítását. Ha a felhasználó már rendelkezik engedéllyel az írásvédett attribútum módosítására, és a felhasználó eltávolítja a fájlt, a Force paraméter használata leegyszerűsíti a műveletet. Ha azonban a felhasználónak nincs engedélye a fájl eltávolítására, a Force paraméternek nincs hatása.

Hitelesítő adatok kezelése a Windows PowerShellen (AD03) keresztül

A parancsmagnak meg kell adnia egy paramétert Credential a hitelesítő adatok megjelenítéséhez. Ennek a paraméternek System.Management.Automation.PSCredential típusúnak kell lennie, és hitelesítőadat-attribútum deklarációval kell definiálni. Ez a támogatás automatikusan kéri a felhasználót a felhasználónévre, a jelszóra vagy mindkettőre, ha a teljes hitelesítő adatot nem adja meg közvetlenül. A Hitelesítő attribútummal kapcsolatos további információkért lásd: Hitelesítőadat-attribútum deklarációja.

Kódolási paraméterek támogatása (AD04)

Ha a parancsmag bináris űrlapra olvas vagy ír szöveget, például fájlba ír vagy olvas egy fájlrendszerben lévő fájlt, akkor a parancsmagnak kódolási paraméterrel kell rendelkeznie, amely meghatározza a szöveg bináris formában való kódolását.

A teszt parancsmagoknak logikai értéket kell visszaadnia (AD05)

Az erőforrásokon végzett teszteket végző parancsmagoknak system.logikai típust kell visszaadniuk a folyamatnak, hogy feltételes kifejezésekben is használhatók legyenek.

Kód irányelvei

A parancsmagkód írásakor az alábbi irányelveket kell figyelembe venni. Ha olyan iránymutatást talál, amely a helyzetére vonatkozik, mindenképpen tekintse meg a hasonló irányelvekre vonatkozó tervezési irányelveket.

Parancsmagosztály elnevezési konvenciók (AC01) követése

A szabványos elnevezési konvenciók követésével felderíthetőbbé teheti a parancsmagokat, és segít a felhasználónak megérteni, hogy pontosan mit csinálnak a parancsmagok. Ez a gyakorlat különösen fontos a Windows PowerShellt használó többi fejlesztő számára, mivel a parancsmagok nyilvános típusok.

Parancsmag definiálása a helyes névtérben

A parancsmag osztályát általában egy .NET-keretrendszerbeli névtérben definiálja, amely hozzáfűzi .Commands azt a névteret, amely azt a terméket jelöli, amelyben a parancsmag fut. A Windows PowerShellben található parancsmagok például a Microsoft.PowerShell.Commands névtérben vannak definiálva.

A parancsmagosztály elnevezése a parancsmag nevének megfelelően

Amikor elnevezi a parancsmagot megvalósító .NET-keretrendszer osztályt, nevezze el az osztályt <Verb><Noun>Command, ahol a <Verb> helyőrzőket a <Noun> parancsmag nevéhez használt igére és főnévre cseréli. A Get-Process parancsmagot például egy úgynevezett GetProcessCommandosztály implementálja.

Ha nincs folyamatbemenet felülbírálja a BeginProcessing metódust (AC02)

Ha a parancsmag nem fogadja el a folyamat bemenetét, a feldolgozást a System.Management.Automation.Cmdlet.BeginProcessing metódusban kell végrehajtani. Ennek a módszernek a használata lehetővé teszi, hogy a Windows PowerShell fenntartsa a parancsmagok közötti sorrendet. A folyamat első parancsmagja mindig visszaadja az objektumait, mielőtt a folyamat többi parancsmagja megkezdené a feldolgozást.

A leállítási kérelmek kezeléséhez felülbírálja a StopProcessing metódust (AC03)

Bírálja felül a System.Management.Automation.Cmdlet.StopProcessing metódust , hogy a parancsmag kezelni tudja a stopjelet. Egyes parancsmagok hosszú időt vesznek igénybe a művelet elvégzéséhez, és hosszú időt hagynak a Windows PowerShell-futtatókörnyezetbe irányuló hívások között, például amikor a parancsmag blokkolja a szálat a hosszan futó RPC-hívásokban. Ide tartoznak azok a parancsmagok, amelyek a System.Management.Automation.Cmdlet.WriteObject metódushoz, a System.Management.Automation.Cmdlet.WriteError metódushoz, valamint más visszajelzési mechanizmusokhoz küldenek hívásokat, amelyek végrehajtása hosszú időt vehet igénybe. Ilyen esetekben előfordulhat, hogy a felhasználónak leállítási jelet kell küldenie ezekhez a parancsmagokhoz.

Az IDisposable Interface (AC04) implementálása

Ha a parancsmag olyan objektumokkal rendelkezik, amelyeket a System.Management.Automation.Cmdlet.ProcessRecord metódus nem távolít el (a folyamatba ír), a parancsmag további objektumelhelyezést igényelhet. Ha például a parancsmag megnyit egy fájlleírót a System.Management.Automation.Cmdlet.BeginProcessing metódusban, és a System.Management.Automation.Cmdlet.ProcessRecord metódus számára nyitva tartja a leírót, a leírót a feldolgozás végén le kell zárni.

A Windows PowerShell-futtatókörnyezet nem mindig hívja meg a System.Management.Automation.Cmdlet.EndProcessing metódust . Előfordulhat például, hogy a System.Management.Automation.Cmdlet.EndProcessing metódus nem hívható meg, ha a parancsmagot a művelet közben félúton megszakítják, vagy ha a parancsmag bármely részén megszűnik a hiba. Ezért egy objektumtisztítást igénylő parancsmag .NET-keretrendszerosztályának implementálnia kell a teljes System.IDisposable felületmintát, beleértve a véglegesítőt is, hogy a Windows PowerShell-futtatókörnyezet meghívhassa a System.Management.Automation.Cmdlet.EndProcessing és a System.IDisposable.Dispose* metódust a feldolgozás végén.

Szerializációbarát paramétertípusok használata (AC05)

A parancsmag távoli számítógépeken való futtatásának támogatásához használjon olyan típusokat, amelyek szerializálhatók az ügyfélszámítógépen, majd rehidratálhatók a kiszolgáló számítógépén. A következő típusok szerializálás-barátak.

Primitív típusok:

• Bájt, SByte, Decimális, Egy, Dupla, Int16, Int32, Int64, Uint16, UInt32 és UInt64.
• Logikai, Guid, Bájt[], TimeSpan, DateTime, Uri és Verzió.
• Karakter, sztring, XmlDocument.

Beépített rehidratálható típusok:

• PSPrimitiveDictionary
• kapcsolóParaméter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Egyéb típusok:

• Biztonságos karakterlánc
• Tárolók (a fenti típusú listák és szótárak)

SecureString használata bizalmas adatokhoz (AC06)

Bizalmas adatok kezelésekor mindig a System.Security.SecureString adattípust használja. Ez magában foglalhatja a paraméterek folyamatbemenetét, valamint a bizalmas adatok visszaadását a folyamatba.

Bár a .NET javasolja a SecureString használatát az új fejlesztéshez, a PowerShell továbbra is támogatja a SecureString osztályt a visszamenőleges kompatibilitás érdekében. A SecureString használata még mindig biztonságosabb, mint egy egyszerű szöveges sztring használata. A PowerShell továbbra is a SecureString típusra támaszkodik, hogy elkerülje a tartalom véletlen felfedését a konzolon vagy a naplókban. Körültekintően használja a SecureStringet , mert könnyen átalakítható egyszerű szöveges sztringgé. A SecureString használatáról a System.Security.SecureString osztály dokumentációjában olvashat bővebben.

Lásd még:

szükséges fejlesztési irányelvek

erősen bátorított fejlesztési iránymutatások

Windows PowerShell-parancsmag írása