PSScriptAnalyzer-Regeln und Empfehlungen

Die folgenden Richtlinien stammen aus einem kombinierten Aufwand sowohl aus dem PowerShell-Team als auch aus der Community. Die Richtlinien sind nach Typ organisiert. Innerhalb jedes Typs gibt es eine Liste von Regeln. Die Regeln werden nach der Schweregrad- gruppiert, die in der Implementierung der PSScriptAnalyzer Regel definiert ist. Die angegebene TBD Schwerestufe bedeutet "Noch zu bestimmen." Gegenstände, die als TBD gekennzeichnet sind, sind Empfehlungen, die derzeit keine festgelegten Regeln haben.

Cmdlet-Entwurfsregeln

Schweregrad: Fehler

Es wurden keine Regeln definiert.

Schweregrad: Warnung

• Verwenden sie nur genehmigte Verben UseApprovedVerbs
• Cmdlets-Namen mit nicht verwendbaren Zeichen AvoidReservedCharInCmdlet-
• Parameternamen, die nicht verwendet werden können, AvoidReservedParams
• Supportbestätigungsanfragen UseShouldProcessForStateChangingFunctions und UseSupportsShouldProcess
• Muss ShouldProcess aufrufen, wenn das attribut ShouldProcess vorhanden ist und umgekehrt UseShouldProcess
• Nomen sollten singular UseSingularNouns
• Fehlende Modulmanifestfelder MissingModuleManifestField-
  • Version
  • Autor
  • Beschreibung
  • LicenseUri- (für den PowerShell-Katalog)
• Switch-Parameter sollten nicht standardmäßig auf "true" "AvoidDefaultValueSwitchParameter"

Schweregrad: Informationen

Es wurden keine Regeln definiert.

Schweregrad: TBD

• Unterstützen Sie Force Parameter für interaktive Sitzungen. Wenn Ihr Cmdlet interaktiv verwendet wird, stellen Sie immer einen Force Parameter bereit, um die interaktiven Aktionen außer Kraft zu setzen, z. B. Eingabeaufforderungen oder Lesezeilen der Eingabe. Der Force-Parameter ist wichtig, weil er es ermöglicht, dein Cmdlet in nicht-interaktiven Skripten und Hosts zu verwenden.
• Dokumentausgabeobjekte
• Modul muss ladebar sein
• Keine Syntaxfehler
• Nicht aufgelöste Abhängigkeiten sind ein Fehler.
• Abgeleitet von den Cmdlet- oder PSCmdlet-Klassen
• Angeben des Cmdlet-Attributs
• Außerkraftsetzen einer Eingabeverarbeitungsmethode
• Angeben des OutputType-Attributs
• Schreiben einzelner Datensätze in die Pipeline
• Groß-/Kleinschreibung bei Cmdlets berücksichtigen und Groß-/Kleinschreibung beibehalten

Skriptfunktionen

Schweregrad: Fehler

Es wurden keine Regeln definiert.

Schweregrad: Warnung

• Vermeiden der Verwendung von Aliasen AvoidUsingCmdletAliases
• Vermeiden Sie veraltete WMI-Cmdlets AvoidUsingWMICmdlet-
• Vermeiden Sie die Verwendung leerer catch Blocks AvoidUsingEmptyCatchBlock
• Aufrufen vorhandener Cmdlets mit korrekten Parametern UseCmdlet Fälschlicherweise
• Cmdlets sollten über ShouldProcess/ShouldContinue und Force Parameter verfügen, wenn bestimmte vom System geänderte Verben verwendet werden (Update, Set, Remove, New): UseShouldProcessForStateChangingFunctions
• Vermeiden der Verwendung von Positionsparametern AvoidUsingPositionalParameters
• Vermeiden der Verwendung globaler Variablen AvoidGlobalVars
• Deklarierte Variablen sollten nach der Zuordnung UseDeclaredVarsMoreThanAssignments
• Vermeiden der Verwendung von Invoke-ExpressionAvoidUsingInvokeExpression

Schweregrad: Informationen

Es wurden keine Regeln definiert.

Schweregrad: TBD

• Vermeiden der Verwendung von Clear-Host
• Vermeiden der Verwendung von UNC-Dateipfaden
• Fehlerbehandlung
  • Verwenden von -ErrorAction Stop beim Aufrufen von Cmdlets
  • Verwenden Sie $ErrorActionPreference Set to Stop oder Continue beim Aufrufen von Noncmdlets
  • Vermeiden der Verwendung von Flags zur Behandlung von Fehlern
  • Vermeiden der Verwendung von $?
  • Vermeiden des Testens einer Nullvariablen als Fehlerbedingung
  • Kopieren von $Error[0] in ihre eigene Variable
• Vermeiden der Verwendung von Pipelines in Skripts
• Wenn ein Rückgabetyp deklariert wird, muss das Cmdlet diesen Typ zurückgeben. Wenn ein Typ zurückgegeben wird, muss ein Rückgabetyp deklariert werden.

Skriptformatvorlage

Schweregrad: Fehler

Es wurden keine Regeln definiert.

Schweregrad: Warnung

• Vermeiden Sie die Verwendung von Write-Host, es sei denn, Sie möchten AvoidUsingWriteHost-

Schweregrad: Informationen

• Schreiben von kommentarbasierten Hilfe ProvideCommentHelp-

Schweregrad: TBD

• Bereitstellen von Verwendungsbeispielen
• Verwenden des Abschnitts "Notizen" für Details zur Funktionsweise des Tools
• Jeder exportierte Befehl sollte Hilfe (einschließlich Parameterdokumentation) haben.
• Dokumentieren Sie die Version von PowerShell, für die das Skript geschrieben wurde
• Einzug des Codes
• Vermeiden von Backticks

Skriptsicherheit

Schweregrad: Fehler

• Vermeiden der Verwendung von Nur-Text-Kennwörtern AvoidUsingPlainTextForPassword-
• Vermeiden Sie -Username und -Password Parameter (verwenden Sie stattdessen PSCredential): UsePSCredentialType
• Vermeiden Sie die Hardcodierung eines -ComputerName Parameterarguments (Informationsentdeckung): AvoidUsingComputerNameHardcoded
• Vermeiden Sie die Verwendung von ConvertTo-SecureString mit Nur-Text (Informationsausgabe): AvoidUsingConvertToSecureStringWithPlainText

Schweregrad: Warnung

• Vermeiden Sie die Verwendung von $Password = 'string' (Offenlegung von Informationen). AvoidUsingUsernameAndPasswordParams

Schweregrad: Informationen

Es wurden keine Regeln definiert.

Schweregrad: TBD

• Vermeiden Sie die Initialisierung von API-Schlüssel- und Zugangsdaten (Informationsoffenlegung)

DSC-verwandte Regeln

Schweregrad: Fehler

• Verwenden von Standard-DSC-Methoden StandardDSCFunctionsInResource-
• Verwenden Sie identische obligatorische Parameter für alle DSC-Methoden UseIdenticalMandatoryParametersForDSC
• Verwenden Sie identische Parameter für set- und Test-DSC-Methoden UseIdenticalParametersForDSC-

Schweregrad: Warnung

Es wurden keine Regeln definiert.

Schweregrad: Informationen

• Die folgenden drei Empfehlungen werden von der regel ReturnCorrectTypesForDSCFunctions abgedeckt.
  • Vermeiden Sie das Zurückgeben eines Objekts aus einer Set-TargetResource- oder Set-Funktion (Class Based)
  • Zurückgeben eines booleschen Werts aus einer Test-TargetResource- oder Testfunktion (Class Based)
  • Zurückgeben eines Objekts aus einer Get-TargetResource- oder Get-Funktion (Class Based)
• DSC-Ressourcen sollten DSC-Tests DSCTestsPresent
• DSC-Ressourcen sollten DSC-Beispiele DSCExamplesPresent

Schweregrad: TBD

• Für Windows PowerShell v4 sollten Ressourcenmodule für jede Ressource eine .psd1 und-Datei schema.mof enthalten
• Ressourcenmodule sollten über eine .psd1 Datei (immer) verfügen und schema.mof (für ressourcenfremde Ressourcen) siehe Problem Nr. 116
• Das Ressourcenmodul sollte einen DscResources-Ordner haben, der die Ressourcen enthält – siehe Ausgabe #130
• MOFs sollten eine Beschreibung für jedes Element haben – siehe Problem Nr. 131
• Verwenden von ShouldProcess- für eine Set DSC-Methode

Referenzen

• -Cmdlet-Entwicklungsrichtlinien
• PowerShell DSC-Ressourcenentwurfs- und Testprüfliste
• DSC-Richtlinien finden Sie auch im DSC-Ressourcen-Repository
  • Richtlinien für DSC-Ressourcenstile & bewährte Methoden
  • DSC-Ressourcenbenennung
  • Erstellen eines hochwertigen DSC-Ressourcenmoduls
• Das inoffizielle PowerShell Best Practices and Style Guide