Verwenden von PSScriptAnalyzer

In diesem Artikel werden verschiedene Funktionen von PSScriptAnalyzer und deren Verwendung beschrieben.

Parser-Fehler

Ab Version 1.18.0 gibt PSScriptAnalyzer Parserfehler als Diagnosedatensätze im Ausgabedatenstrom aus.

Invoke-ScriptAnalyzer -ScriptDefinition '"b" = "b"; function eliminate-file () { }'

RuleName            Severity   ScriptName Line Message
--------            --------   ---------- ---- -------
InvalidLeftHandSide ParseError            1    The assignment expression isn't
                                               valid. The input to an
                                               assignment operator must be an
                                               object that's able to accept
                                               assignments, such as a variable
                                               or a property.
PSUseApprovedVerbs  Warning               1    The cmdlet 'eliminate-file' uses an
                                               unapproved verb.

Der RuleName wird auf die ErrorId des Parserfehlers festgelegt.

Um ParseErrors zu unterdrücken, fügen Sie es nicht als Wert in den Schweregrad-Parameter ein.

$invokeScriptAnalyzerSplat = @{
    ScriptDefinition = '"b" = "b"; function eliminate-file () { }'
    Severity = 'Warning'
}
Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat

RuleName           Severity ScriptName Line Message
--------           -------- ---------- ---- -------
PSUseApprovedVerbs Warning             1    The cmdlet 'eliminate-file' uses an
                                            unapproved verb.

Unterdrücken von Regeln

Sie können eine Regel unterdrücken, indem Sie ein Skript, eine Funktion oder einen Parameter mit . NET verwenden. Der Konstruktor für SuppressMessageAttribute akzeptiert zwei Parameter: eine Kategorie und eine Prüf-ID. Legen Sie den categoryID-Parameter auf den Namen der Regel fest, die Sie unterdrücken möchten, und legen Sie den checkID-Parameter auf eine NULL- oder leere Zeichenfolge fest. Optional können Sie einen dritten benannten Parameter mit einer Begründung für die Unterdrückung der Nachricht hinzufügen:

function SuppressMe()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideCommentHelp', '',
        Justification='Just an example')]
    param()

    Write-Verbose -Message "I'm making a difference!"

}

Innerhalb des Bereichs des Skripts, der Funktion oder des Parameters, den Sie angepasst haben, werden alle Regelverstöße unterdrückt.

Um eine Meldung für einen bestimmten Parameter zu unterdrücken, legen Sie den CheckId-Parameter von SuppressMessageAttribute auf den Namen des Parameters fest:

function SuppressTwoVariables()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideDefaultParameterValue', 'b')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideDefaultParameterValue', 'a')]
    param([string]$a, [int]$b)
    {
    }
}

Verwenden Sie die Scope-Eigenschaft von SuppressMessageAttribute , um die Regelunterdrückung auf Funktionen oder Klassen innerhalb des Bereichs des Attributs zu beschränken.

Verwenden Sie den Wert Function , um Verstöße gegen alle Funktionen innerhalb des Bereichs des Attributs zu unterdrücken. Verwenden Sie den Wert Class , um Verstöße für alle Klassen innerhalb des Bereichs des Attributs zu unterdrücken:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideCommentHelp', '', Scope='Function')]
param()

function InternalFunction
{
    param()

    Write-Verbose -Message "I am invincible!"
}

Sie können die Unterdrückung zusätzlich auf Basis des Funktions-, Parameter-, Klassen-, Variablen- oder Objektnamens einschränken, indem Sie die Target-Eigenschaft von SuppressMessageAttribute auf einen regulären Ausdruck oder ein Wildcard-Muster setzen.

So unterdrücken Sie z. B. den Verstoß gegen die PSAvoidUsingWriteHost-Regel in start-bar und start-baz , aber nicht in start-foo und start-bam:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='start-ba[rz]')]
param()
function start-foo {
    write-host "start-foo"
}

function start-bar {
    write-host "start-bar"
}

function start-baz {
    write-host "start-baz"
}

function start-bam {
    write-host "start-bam"
}

So unterdrücken Sie Verstöße in allen Funktionen:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='*')]
Param()

Um Verstöße in start-barzu unterdrücken, start-baz aber start-bam nicht in start-foo:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='start-b*')]
Param()

Hinweis

Parserfehler können nicht mit SuppressMessageAttribute unterdrückt werden.

Unterstützung von Einstellungen in ScriptAnalyzer

Sie können Einstellungen erstellen, die die ScriptAnalyzer-Regeln beschreiben, die basierend auf dem Schweregrad ein- oder ausgeschlossen werden sollen. Verwenden Sie den Parameter Einstellungen von Invoke-ScriptAnalyzer , um die Konfiguration anzugeben. Der Einstellungsparameter ermöglicht es dir, eine benutzerdefinierte Konfiguration für eine bestimmte Umgebung zu erstellen. ScriptAnalyzer unterstützt folgende Modi zur Spezifikation der Einstellungsdatei:

Eingebaute Presets

ScriptAnalyzer enthält eine Reihe integrierter Voreinstellungen, die zum Analysieren von Skripts verwendet werden können. Wenn Sie z. B . PowerShell-Katalogregeln für Ihr Modul ausführen möchten, verwenden Sie den folgenden Befehl:

Invoke-ScriptAnalyzer -Path /path/to/module/ -Settings PSGallery -Recurse

Darüber hinaus können Sie andere integrierte Voreinstellungen verwenden, z. B. DSC und CodeFormatting. Diese Voreinstellungen können für den Parameter Einstellungen mit der Tabulatortaste vervollständigt werden.

Explicit

Im folgenden Beispiel werden zwei Regeln aus dem Standardregelsatz sowie alle Regeln mit einem anderen Schweregrad als Fehler und Warnung ausgeschlossen.

# PSScriptAnalyzerSettings.psd1
@{
    Severity=@('Error','Warning')
    ExcludeRules=@('PSAvoidUsingCmdletAliases', 'PSAvoidUsingWriteHost')
}

Sie können diese Einstellungsdatei dann aufrufen mit Invoke-ScriptAnalyzer:

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1

Im nächsten Beispiel werden anstelle aller Standardregeln einige Regeln ausgewählt, die ausgeführt werden sollen.

# PSScriptAnalyzerSettings.psd1
@{
    IncludeRules=@('PSAvoidUsingPlainTextForPassword',
                'PSAvoidUsingConvertToSecureStringWithPlainText')
}

Sie können diese Einstellungsdatei dann aufrufen:

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1

Implizit

Wenn Sie eine Einstellungsdatei mit einem Namen PSScriptAnalyzerSettings.psd1 im Projektstamm platzieren, wird sie von PSScriptAnalyzer erkannt, wenn Sie den Projektstamm als Pfadparameter übergeben.

Invoke-ScriptAnalyzer -Path "C:\path\to\project" -Recurse

Die explizit Bereitstellung von Einstellungen hat höhere Priorität als dieser implizite Modus. Beispiel-Einstellungsdateien finden Sie im Settings Ordner des PSScriptAnalyzer-Moduls .

Überprüfen der Kompatibilität der PowerShell-Version

PSScriptAnalyzer kann PowerShell-Skripts auf Inkompatibilitäten mit anderen PowerShell-Versionen und -Umgebungen überprüfen. PSScriptAnalyzer enthält vier Regeln, die nach Kompatibilitätsproblemen suchen:

• PSUseCompatibleCmdlets überprüft, ob Cmdlets, die in einem Skript verwendet werden, in anderen PowerShell-Umgebungen verfügbar sind
• PSUseCompatibleCommands überprüft, ob Befehle, die in einem Skript verwendet werden, in anderen PowerShell-Umgebungen verfügbar sind
• PSUseCompatibleSyntax prüft, ob eine in einem Skript verwendete Syntax auch in anderen PowerShell-Versionen kompatibel ist
• PSUseCompatibleTypes überprüft, ob .NET-Typen und statische Methoden oder Eigenschaften in anderen PowerShell-Umgebungen verfügbar sind

Weitere Informationen zur Verwendung dieser Regeln finden Sie unter Verwenden von PSScriptAnalyzer zum Überprüfen der PowerShell-Versionskompatibilität im PowerShell Team-Blog.

Benutzerdefinierte Regeln

Es ist möglich, einen oder mehrere Pfade zu benutzerdefinierten Regeln in der Einstellungsdatei anzugeben. Es ist wichtig, dass diese Pfade entweder auf den Ordner eines Moduls verweisen, der implizit das Modulmanifest verwendet, oder auf die Skriptdatei des Moduls (.psm1). Das Modul muss die benutzerdefinierten Regelfunktionen mit Export-ModuleMember exportieren, damit sie für PSScriptAnalyzer verfügbar sind.

In diesem Beispiel weist die CustomRulePath-Eigenschaft auf zwei verschiedene Module hin. Beide Module exportieren die Regelfunktionen mit dem Verb Measure , so dass Measure-* für die Eigenschaft IncludeRules verwendet wird.

@{
    CustomRulePath      = @(
        '.\output\RequiredModules\DscResource.AnalyzerRules'
        '.\tests\QA\AnalyzerRules\SqlServerDsc.AnalyzerRules.psm1'
    )

    IncludeRules        = @(
        'Measure-*'
    )
}

Sie können auch Standardregeln hinzufügen, indem Sie die Regeln in der IncludeRules-Eigenschaft auflisten. Wenn Sie Standardregeln einschließen, ist es wichtig, dass Sie die Eigenschaft IncludeDefaultRules auf $truefestlegen, andernfalls werden die Standardregeln verwendet.

@{
    CustomRulePath      = @(
        '.\output\RequiredModules\DscResource.AnalyzerRules'
        '.\tests\QA\AnalyzerRules\SqlServerDsc.AnalyzerRules.psm1'
    )

    IncludeDefaultRules = $true

    IncludeRules        = @(
        # Default rules
        'PSAvoidDefaultValueForMandatoryParameter'
        'PSAvoidDefaultValueSwitchParameter'

        # Custom rules
        'Measure-*'
    )
}

Verwendung benutzerdefinierter Regeln in Visual Studio Code (VS Code)

Du kannst auch die benutzerdefinierten Regeln verwenden, die in der Einstellungsdatei in VS Code bereitgestellt werden. Füge eine VS Code-Workspace-Einstellungsdatei (.vscode/settings.json) mit folgendem Inhalt hinzu.

{
    "powershell.scriptAnalysis.settingsPath": ".vscode/analyzersettings.psd1",
    "powershell.scriptAnalysis.enable": true,
}

ScriptAnalyzer als .NET-Bibliothek

Sie können die Engine und die Funktionen von ScriptAnalyzer direkt als Bibliothek nutzen.

Hier sind die öffentlichen Schnittstellen:

using Microsoft.Windows.PowerShell.ScriptAnalyzer;

public void Initialize(System.Management.Automation.Runspaces.Runspace runspace,
Microsoft.Windows.PowerShell.ScriptAnalyzer.IOutputWriter outputWriter,
[string[] customizedRulePath = null],
[string[] includeRuleNames = null],
[string[] excludeRuleNames = null],
[string[] severity = null],
[bool suppressedOnly = false],
[string profile = null])

public System.Collections.Generic.IEnumerable<DiagnosticRecord> AnalyzePath(string path,
    [bool searchRecursively = false])

public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames,
    string[] ruleNames)

Korrektur von Verstößen

Du kannst den Korrektur-Schalter verwenden, um automatisch verstoßende Inhalte durch eine vorgeschlagene Alternative zu ersetzen. Da Invoke-ScriptAnalyzerSupportsShouldProcess implementiert wird, können Sie außerdem WhatIf oder Confirm verwenden, um herauszufinden, welche Korrekturen angewendet werden. Sie sollten Quellcode-Kontrolle verwenden, wenn Sie Korrekturen anwenden, da einige Änderungen, wie zum Beispiel die für AvoidUsingPlainTextForPassword, möglicherweise weitere Skriptänderungen erfordern, die nicht automatisch vorgenommen werden können. Die anfängliche Codierung kann nicht immer erhalten bleiben, wenn man Vorschläge automatisch anwendet. Du solltest die Dateikodierung überprüfen, ob deine Skripte von einer bestimmten Codierung abhängen.

Die SuggestedCorrections-Eigenschaft des Fehlereintrags ermöglicht schnelle Lösungsszenarien in Editoren wie VS Code. Wir stellen gültige SuggestedCorrection für die folgenden Regeln bereit:

• VermeidenAlias
• VermeidenVerwendenPlainTextForPassword
• IrreführendBacktick
• MissingModuleManifestField
• UseToExportFieldsInManifest