Rekommenderade riktlinjer för utveckling
I det här avsnittet beskrivs riktlinjer som du bör överväga för att säkerställa en bra utvecklings- och användarupplevelse. Ibland kan de gälla, och ibland kanske de inte gör det.
Designriktlinjer
Följande riktlinjer bör beaktas när du utformar cmdlets. När du hittar en designriktlinjer 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.
Stop-ProcExempel-cmdleten i StopProc Tutorial definierar till exempel en parameter av typen InputObject 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 till Stop-Proc cmdleten direkt.
Stöd för force-parametern (AD02)
Ibland behöver 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.
Till exempel tar cmdleten Remove-Item normalt inte bort en skrivskyddad fil. Den här cmdleten stöder dock en Force-parameter så att en användare kan framtända 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 deklaration av autentiseringsattribut. Det här stödet uppmanar automatiskt användaren att ange användarnamnet, lösenordet eller båda när en fullständig autentiseringsidentifiering 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 format, till exempel att skriva till eller läsa från en fil i ett filsystem, måste cmdleten ha en Encoding-parameter som anger hur texten kodas i binärformatet.
Test-cmdlets bör returnera ett booleskt (AD05)
Cmdlets som utför tester mot sina resurser bör returnera en System.Boolean-typ till pipelinen så att de kan användas i villkorsuttryck.
Riktlinjer för kod
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-klasser (AC01)
Genom att följa standardkonventionerna för namngivning gör du dina cmdlets mer identifieringsbara och hjälper användaren att förstå exakt vad cmdletarna gör. Den här praxis är särskilt viktig för andra utvecklare som använder Windows PowerShell eftersom cmdlets är offentliga typer.
Definiera en cmdlet i rätt namnområde
Normalt definierar du klassen för en cmdlet i en .NET Framework som lägger till ". Kommandon" till det namnområde som representerar den produkt där cmdleten körs. Till exempel definieras cmdlets som ingår Windows PowerShell i Microsoft.PowerShell.Commands namnområdet.
Namnge cmdlet-klassen så att den matchar cmdletens namn
När du ger klassen .NET Framework som implementerar en cmdlet ger du klassen namnet " ", där du ersätter platshållarna och med verbet och substantivet som används för <Verb><Noun><Command> <Verb> <Noun> cmdletnamnet. Till exempel implementeras cmdleten Get-Process av en klass som heter GetProcessCommand .
Om inga pipelineindata åsidosätter beginProcessing-metoden (AC02)
Om cmdleten inte accepterar indata från pipelinen ska bearbetningen implementeras i metoden System.Management.Automation.Cmdlet.BeginProcessing. Med den här metoden kan Windows PowerShell upprätthålla ordningen mellan cmdlets. Den första cmdleten i pipelinen returnerar alltid objekten 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 din cmdlet kan hantera stoppsignalen. Vissa cmdlets tar lång tid att slutföra åtgärden och de låter 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 inkluderar cmdlets som gör anrop till 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 cmdlets.
Implementera AC04 (IInterosable Interface)
Om cmdleten innehåller objekt som inte tas bort (skrivs till pipelinen) av metoden System.Management.Automation.Cmdlet.ProcessRecord kan cmdleten kräva ytterligare objektförsämring. Om din cmdlet till exempel öppnar en filhanterare i metoden System.Management.Automation.Cmdlet.BeginProcessing och håller referensen öppen för användning av metoden System.Management.Automation.Cmdlet.ProcessRecord måste den här referensen stängas i slutet av bearbetningen.
Den Windows PowerShell runtime anropar inte alltid metoden System.Management.Automation.Cmdlet.EndProcessing. Metoden System.Management.Automation.Cmdlet.EndProcessing kanske till exempel inte anropas om cmdleten avbryts mitt i å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 gränssnittsmönstret System.IInterosable, inklusive slutföraren, så att Windows PowerShell-körningen kan anropa både metoderna System.Management.Automation.Cmdlet.EndProcessing och System.IInterosable.Dispose* i slutet av bearbetningen.
Använda serialiseringsvänliga parametertyper (AC05)
För att ge stöd för att köra cmdleten på fjärrdatorer använder du typer som enkelt kan serialiseras på klientdatorn och sedan rehydreras 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 rehydratbara typer:
PSPrimitiveDictionary
SwitchParameter
PSListModifier
PSCredential
IPAddress, MailAddress
CultureInfo
X509Certificate2, X500DistinguishedName
DirectorySecurity, FileSecurity, RegistrySecurity
Andra typer:
SecureString
Containrar (listor och ordlistor av ovanstående typ)
Använda SecureString för känsliga data (AC06)
Använd alltid datatypen System.Security.Securestring när du hanterar känsliga data. Detta kan omfatta pipelineindata till parametrar och returnera känsliga data till pipelinen.
Se även
Obligatoriska riktlinjer för utveckling
Feedback
Skicka och visa feedback för