Riktlinjer för rådgivande utveckling

I det här avsnittet beskrivs riktlinjer som du bör överväga för att säkerställa god utveckling och användarupplevelser. Ibland kan de gälla, och ibland kanske de inte gör det.

Designriktlinjer

Följande riktlinjer bör beaktas när du utformar cmdletar. När du hittar en designguide som gäller för din situation bör du titta på riktlinjerna för kod för liknande riktlinjer.

Stöd för en InputObject-parameter (AD01)

Eftersom Windows PowerShell fungerar direkt med Microsoft .NET Framework-objekt är ett .NET Framework-objekt ofta tillgängligt som exakt matchar den typ som användaren behöver för att utföra en viss åtgärd. InputObject är standardnamnet för en parameter som tar ett sådant objekt som indata. Exempel-cmdleten Stop-Proc i StopProc-självstudien definierar till exempel en InputObject parameter av typen Process som stöder indata från pipelinen. Användaren kan hämta en uppsättning processobjekt, ändra dem för att välja de exakta objekt som ska stoppas och sedan skicka dem direkt till cmdleten Stop-Proc .

Stöd för Force Parameter (AD02)

Ibland måste en cmdlet skydda användaren från att utföra en begärd åtgärd. En sådan cmdlet bör ha stöd för en Force-parameter så att användaren kan åsidosätta skyddet om användaren har behörighet att utföra åtgärden.

Cmdleten Remove-Item tar till exempel normalt inte bort en skrivskyddad fil. Den här cmdleten stöder dock en Force-parameter så att en användare kan tvinga fram borttagning av en skrivskyddad fil. Om användaren redan har behörighet att ändra det skrivskyddade attributet och användaren tar bort filen förenklar användningen av force-parametern åtgärden. Men om användaren inte har behörighet att ta bort filen har force-parametern ingen effekt.

Hantera autentiseringsuppgifter via Windows PowerShell (AD03)

En cmdlet ska definiera en Credential parameter som representerar autentiseringsuppgifter. Den här parametern måste vara av typen System.Management.Automation.PSCredential och måste definieras med hjälp av en autentiseringsattributdeklaration. Det här stödet uppmanar automatiskt användaren att ange användarnamnet, lösenordet eller båda när en fullständig autentiseringsuppgift inte anges direkt. Mer information om attributet Autentiseringsuppgifter finns i Deklaration av attribut för autentiseringsuppgifter.

Stöd för kodningsparametrar (AD04)

Om din cmdlet läser eller skriver text till eller från ett binärt formulär, till exempel skriva till eller läsa från en fil i ett filsystem, måste din cmdlet ha en kodningsparameter som anger hur texten kodas i binärt format.

Test-cmdletar ska returnera ett booleskt värde (AD05)

Cmdletar som utför tester mot sina resurser bör returnera en System.Boolesk typ till pipelinen så att de kan användas i villkorsuttryck.

Kodriktlinjer

Följande riktlinjer bör beaktas när du skriver cmdlet-kod. När du hittar en riktlinje som gäller för din situation bör du titta på designriktlinjerna för liknande riktlinjer.

Följ Namngivningskonventioner för cmdlet-klass (AC01)

Genom att följa vanliga namngivningskonventioner gör du dina cmdletar mer identifierbara och hjälper användaren att förstå exakt vad cmdletarna gör. Den här metoden är särskilt viktig för andra utvecklare som använder Windows PowerShell eftersom cmdletar är offentliga typer.

Definiera en cmdlet i rätt namnområde

Normalt definierar du klassen för en cmdlet i ett .NET Framework-namnområde som lägger .Commands till i namnområdet som representerar den produkt där cmdleten körs. Till exempel definieras cmdletar som ingår i Windows PowerShell i Microsoft.PowerShell.Commands namnområdet.

Namnge cmdlet-klassen så att den matchar cmdletens namn

När du namnger .NET Framework-klassen som implementerar en cmdlet, namnger du klassen <Verb><Noun>Command, där du ersätter <Verb> platshållarna och <Noun> med verbet och substantivet som används för cmdlet-namnet. Get-Process-cmdleten implementeras till exempel av en klass med namnet .GetProcessCommand

Om ingen pipelineindata åsidosätter Metoden BeginProcessing (AC02)

Om cmdleten inte accepterar indata från pipelinen bör bearbetningen implementeras i metoden System.Management.Automation.Cmdlet.BeginProcessing . Med den här metoden kan Windows PowerShell behålla ordningen mellan cmdletar. Den första cmdleten i pipelinen returnerar alltid sina objekt innan de återstående cmdletarna i pipelinen får en chans att påbörja bearbetningen.

Om du vill hantera stoppbegäranden åsidosätter du metoden StopProcessing (AC03)

Åsidosätt metoden System.Management.Automation.Cmdlet.StopProcessing så att cmdleten kan hantera stoppsignalen. Vissa cmdletar tar lång tid att slutföra sin åtgärd, och de låter en lång tid passera mellan anrop till Windows PowerShell-körningen, till exempel när cmdleten blockerar tråden i långvariga RPC-anrop. Detta omfattar cmdletar som anropar metoden System.Management.Automation.Cmdlet.WriteObject , till metoden System.Management.Automation.Cmdlet.WriteError och till andra feedbackmekanismer som kan ta lång tid att slutföra. I dessa fall kan användaren behöva skicka en stoppsignal till dessa cmdletar.

Implementera IDisposable Interface (AC04)

Om cmdleten har objekt som inte tas bort (skrivs till pipelinen) av metoden System.Management.Automation.Cmdlet.ProcessRecord kan cmdleten kräva ytterligare bortskaffande av objekt. Om din cmdlet till exempel öppnar en filreferens i metoden System.Management.Automation.Cmdlet.BeginProcessing och håller handtaget öppet för användning av metoden System.Management.Automation.Cmdlet.ProcessRecord måste det här handtaget stängas i slutet av bearbetningen.

Windows PowerShell-körningen anropar inte alltid metoden System.Management.Automation.Cmdlet.EndProcessing . Metoden System.Management.Automation.Cmdlet.EndProcessing kanske inte anropas om cmdleten avbryts halvvägs genom åtgärden eller om ett avslutande fel inträffar i någon del av cmdleten. Därför bör .NET Framework-klassen för en cmdlet som kräver objektrensning implementera det fullständiga mönstret för System.IDisposable-gränssnittet , inklusive finalizern, så att Windows PowerShell-körningen kan anropa både System.Management.Automation.Cmdlet.EndProcessing och System.IDisposable.Dispose* i slutet av bearbetningen.

Använda serialiseringsvänliga parametertyper (AC05)

Om du vill ha stöd för att köra din cmdlet på fjärrdatorer använder du typer som kan serialiseras på klientdatorn och sedan extraheras på serverdatorn. Följande typer är serialiseringsvänliga.

Primitiva typer:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 och UInt64.
• Boolesk, Guid, Byte[], TimeSpan, DateTime, Uri och Version.
• Char, String, XmlDocument.

Inbyggda rehydratable-typer:

• PSPrimitiveDictionary
• SwitchParameter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Andra typer:

• SecureString (SäkerSträng)
• Containrar (listor och ordlistor av ovanstående typ)

Använda SecureString för känsliga data (AC06)

När du hanterar känsliga data använder du alltid datatypen System.Security.SecureString . Detta kan omfatta pipelineindata till parametrar samt att returnera känsliga data till pipelinen.

Även om .NET rekommenderar att du inte använder SecureString för ny utveckling fortsätter PowerShell att stödja Klassen SecureString för bakåtkompatibilitet. Att använda en SecureString är fortfarande säkrare än att använda en oformaterad textsträng. PowerShell förlitar sig fortfarande på typen SecureString för att undvika att oavsiktligt exponera innehållet för konsolen eller i loggar. Använd SecureString noggrant eftersom det enkelt kan konverteras till en oformaterad textsträng. En fullständig diskussion om hur du använder SecureString finns i klassdokumentationen System.Security.SecureString.

Se även

nödvändiga riktlinjer för utveckling

starkt uppmuntrade riktlinjer för utveckling

Skriva en Windows PowerShell-cmdlet