Freigeben über


Invoke-ScriptAnalyzer

Wertet ein Skript oder Modul basierend auf ausgewählten Bewährten Methodenregeln aus.

Syntax

Invoke-ScriptAnalyzer
      [-Path] <string>
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-SuppressedOnly]
      [-Fix]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]
Invoke-ScriptAnalyzer
      [-Path] <string>
      -IncludeSuppressed
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-Fix]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]
Invoke-ScriptAnalyzer
      [-ScriptDefinition] <string>
      -IncludeSuppressed
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]
Invoke-ScriptAnalyzer
      [-ScriptDefinition] <string>
      [-CustomRulePath <string[]>]
      [-RecurseCustomRulePath]
      [-IncludeDefaultRules]
      [-ExcludeRule <string[]>]
      [-IncludeRule <string[]>]
      [-Severity <string[]>]
      [-Recurse]
      [-SuppressedOnly]
      [-EnableExit]
      [-Settings <Object>]
      [-SaveDscDependency]
      [-ReportSummary]
      [-WhatIf]
      [-Confirm]
      [<CommonParameters>]

Beschreibung

Invoke-ScriptAnalyzer wertet Skripts oder Moduldateien (.ps1, .psm1, und .psd1 Dateien) basierend auf einer Auflistung bewährter Methoden aus und gibt Objekte zurück, die Regelverletzungen darstellen. Es enthält auch spezielle Regeln zum Analysieren von DSC-Ressourcen.

Invoke-ScriptAnalyzer enthält eine Reihe von integrierten Regeln. Standardmäßig werden alle Regeln verwendet. Sie können die Parameter IncludeRule und ExcludeRule verwenden, um die gewünschten Regeln auszuwählen. Sie können das Get-ScriptAnalyzerRule Cmdlet verwenden, um die Regeln zu untersuchen und auszuwählen, die Sie einschließen oder aus der Auswertung ausschließen möchten.

Sie können auch benutzerdefinierte Regeln verwenden, die Sie in PowerShell-Skripts schreiben, oder in Assemblys mit C# kompilieren. Benutzerdefinierte Regeln können auch mit den Parametern IncludeRule und ExcludeRule ausgewählt werden.

Sie können auch eine Regel in die Analyse einschließen, aber die Ausgabe dieser Regel für ausgewählte Funktionen oder Skripts unterdrücken. Dieses Feature sollte nur bei Bedarf verwendet werden. Um unterdrückte Regeln abzurufen, führen Sie mit dem Parameter SuppressedOnly ausInvoke-ScriptAnalyzer.

Für die Verwendung in CI-Systemen beendet EnableExit die Shell mit einem Exitcode, der der Anzahl der Fehlerdatensätze entspricht.

Beispiele

BEISPIEL 1: Ausführen aller Script Analyzer-Regeln für ein Skript

Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1

BEISPIEL 2: Ausführen aller Script Analyzer-Regeln für alle Dateien im Verzeichnis Modules

In diesem Beispiel werden alle Script Analyzer-Regeln für alle .ps1 und .psm1 Dateien in Ihrem benutzerbasierten Modules Verzeichnis und den zugehörigen Unterverzeichnissen ausgeführt.

Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse

BEISPIEL 3: Ausführen einer einzelnen Regel für ein Modul

In diesem Beispiel wird nur die PSAvoidUsingPositionalParameters-Regel für die Dateien im PSDiagnostics Modulordner ausgeführt. Sie können einen Befehl wie diesen verwenden, um alle Instanzen einer bestimmten Regelverletzung zu finden.

Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters

BEISPIEL 4: Ausführen aller Regeln mit Ausnahme von zwei in Ihren Modulen

In diesem Beispiel werden alle Regeln mit Ausnahme von PSAvoidUsingCmdletAliases und PSAvoidUsingInternalURLs für die .ps1 Dateien und .psm1 im Verzeichnis und in den MyModules zugehörigen Unterverzeichnissen ausgeführt.

Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs

BEISPIEL 5: Ausführen von Script Analyzer mit benutzerdefinierten Regeln

In diesem Beispiel wird Script Analyzer Test-Script.ps1 mit den Standardregeln und -regeln im C:\CommunityAnalyzerRules Pfad ausgeführt.

Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules -IncludeDefaultRules

BEISPIEL 6: Führen Sie nur die Regeln aus, die den Fehlerschweregrad aufweisen und den PSDSC-Quellnamen haben.

$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse

BEISPIEL 7: Unterdrücken von Regelverstößen

In diesem Beispiel wird gezeigt, wie die Meldung von Regelverstößen in einer Funktion unterdrückt wird und wie Regelverstöße ermittelt werden, die unterdrückt werden.

Im Beispiel wird das SuppressMessageAttribute -Attribut verwendet, um die Regeln PSUseSingularNouns und PSAvoidUsingCmdletAliases für die Get-Widgets Funktion im Get-Widgets.ps1 Skript zu unterdrücken. Sie können dieses Attribut verwenden, um eine Regel für ein Modul, ein Skript, eine Klasse, eine Funktion, einen Parameter oder eine Zeile zu unterdrücken.

Mit dem ersten Befehl wird Script Analyzer für die Skriptdatei ausgeführt, die die Funktion enthält. Die Ausgabe meldet einen Regelverstoß. Obwohl mehr Regeln verletzt werden, wird keine unterdrückte Regel gemeldet.

function Get-Widgets
{
    [CmdletBinding()]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", Justification="Resolution in progress.")]
    Param()

    dir $pshome
    ...
}

Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1

RuleName                            Severity     FileName   Line  Message
--------                            --------     --------   ----  -------
PSProvideCommentHelp                Information  ManageProf 14    The cmdlet 'Get-Widget' does not have a help comment.
                                                 iles.psm1

Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly

Rule Name                           Severity     File Name  Line  Justification
---------                           --------     ---------  ----  -------------
PSAvoidUsingCmdletAliases           Warning      ManageProf 21    Resolution in progress.
                                                 iles.psm1
PSUseSingularNouns                  Warning      ManageProf 14
                                                 iles.psm1

Der zweite Befehl verwendet den SuppressedOnly-Parameter , um Verstöße gegen die Regeln zu melden, die unterdrückte Skriptdatei sind.

BEISPIEL 8: Analysieren von Skriptdateien mithilfe einer Profildefinition

In diesem Beispiel erstellen wir ein Script Analyzer-Profil und speichern es in der ScriptAnalyzerProfile.txt Datei im aktuellen Verzeichnis. Wir werden für die BitLocker-Moduldateien ausgeführtInvoke-ScriptAnalyzer. Der Wert des Profilparameters ist der Pfad zum Script Analyzer-Profil.

# In .\ScriptAnalyzerProfile.txt
@{
    Severity = @('Error', 'Warning')
    IncludeRules = 'PSAvoid*'
    ExcludeRules = '*WriteHost'
}

Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Profile .\ScriptAnalyzerProfile.txt

Wenn Sie einen in Konflikt stehenden Parameter in den Invoke-ScriptAnalyzer Befehl einschließen, z. B -Severity Error. , verwendet das Cmdlet den Profilwert und ignoriert den Parameter.

BEISPIEL 9: Analysieren eines als Zeichenfolge gespeicherten Skripts

In diesem Beispiel wird der ScriptDefinition-Parameter verwendet, um eine Funktion an der Befehlszeile zu analysieren. Die Funktionszeichenfolge ist in Anführungszeichen eingeschlossen.

Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}"

RuleName                            Severity     FileName   Line  Message
--------                            --------     --------   ----  -------
PSAvoidUsingWriteHost               Warning                 1     Script
                                                                  because
                                                                  there i
                                                                  suppres
                                                                  Write-O
PSUseSingularNouns                  Warning                 1     The cmd
                                                                  noun sh

Wenn Sie den Parameter ScriptDefinition verwenden, ist $nulldie FileName-Eigenschaft des DiagnosticRecord-Objekts .

Parameter

-Confirm

Hiermit werden Sie vor der Ausführung des Cmdlets zur Bestätigung aufgefordert.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CustomRulePath

Geben Sie den Pfad zu einer Datei ein, die Regeln definiert, oder ein Verzeichnis, das Dateien enthält, die Regeln definieren. Platzhalterzeichen werden unterstützt. Wenn CustomRulePath angegeben wird, werden nur die benutzerdefinierten Regeln in den angegebenen Pfaden für die Analyse verwendet. Wenn Invoke-ScriptAnalyzer in keine Regeln gefunden werden können, werden die Standardregeln ohne Hinweis ausgeführt.

Um Regeln hinzuzufügen, die in Unterverzeichnissen des Pfads definiert sind, verwenden Sie den Parameter RecurseCustomRulePath . Fügen Sie zum Einschließen der integrierten Regeln den Parameter IncludeDefaultRules hinzu.

Type:String[]
Aliases:CustomizedRulePath
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:True

-EnableExit

Nach Abschluss der Analyse beendet dieser Parameter die PowerShell-Sitzungen und gibt einen Exitcode zurück, der der Anzahl der Fehlerdatensätze entspricht. Dies kann in der Ci-Pipeline (Continuous Integration) nützlich sein.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ExcludeRule

Entlässt die angegebenen Regeln aus dem Script Analyzer-Test. Platzhalterzeichen werden unterstützt.

Geben Sie eine durch Trennzeichen getrennte Liste von Regelnamen, eine Variable mit Regelnamen oder einen Befehl ein, der Regelnamen abruft. Sie können auch eine Liste ausgeschlossener Regeln in einer Script Analyzer-Profildatei angeben. Sie können Standardregeln und -regeln in einem benutzerdefinierten Regelpfad ausschließen.

Wenn Sie eine Regel ausschließen, wird die Regel für keine der Dateien im Pfad ausgeführt. Um eine Regel für eine bestimmte Zeile, einen Parameter, eine Bestimmte Funktion, ein Skript oder eine bestimmte Klasse auszuschließen, passen Sie den Path-Parameter an, oder unterdrücken Sie die Regel. Informationen zum Unterdrücken einer Regel finden Sie in den Beispielen.

Wenn eine Regel sowohl in der ExcludeRule - als auch in der IncludeRule-Auflistung angegeben wird, wird die Regel ausgeschlossen.

Type:String[]
Position:Named
Default value:All rules are included.
Required:False
Accept pipeline input:False
Accept wildcard characters:True

-Fix

Behebt bestimmte Warnungen, die einen Fix in ihrem DiagnosticRecord enthalten.

Wenn Sie Fix verwendet haben, Invoke-ScriptAnalyzer wendet die Korrekturen vor dem Ausführen der Analyse an. Stellen Sie sicher, dass Sie über eine Sicherung Ihrer Dateien verfügen, wenn Sie diesen Parameter verwenden. Es wird versucht, die Dateicodierung beizubehalten, aber es gibt immer noch einige Fälle, in denen sich die Codierung ändern kann.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludeDefaultRules

Rufen Sie Standardregeln zusammen mit benutzerdefinierten Regeln auf.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludeRule

Führt nur die angegebenen Regeln im Script Analyzer-Test aus. Standardmäßig führt PSScriptAnalyzer alle Regeln aus.

Geben Sie eine durch Trennzeichen getrennte Liste von Regelnamen, eine Variable mit Regelnamen oder einen Befehl ein, der Regelnamen abruft. Platzhalterzeichen werden unterstützt. Sie können auch Regelnamen in einer Script Analyzer-Profildatei angeben.

Wenn Sie den Parameter CustomizedRulePath verwenden, können Sie diesen Parameter verwenden, um Standardregeln und -regeln in die benutzerdefinierten Regelpfade einzuschließen.

Wenn eine Regel sowohl in der ExcludeRule - als auch in der IncludeRule-Auflistung angegeben wird, wird die Regel ausgeschlossen.

Der Schweregradparameter hat Vorrang vor IncludeRule. Wenn der Schweregrad beispielsweise lautet Error, können Sie IncludeRule nicht verwenden, um eine Warning Regel einzuschließen.

Type:String[]
Position:Named
Default value:All rules are included.
Required:False
Accept pipeline input:False
Accept wildcard characters:True

-IncludeSuppressed

Schließen Sie unterdrückte Diagnose in die Ausgabe ein.

Type:SwitchParameter
Position:Named
Default value:False
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Path

Gibt den Pfad zu den zu analysierenden Skripts oder Modulen an. Platzhalterzeichen werden unterstützt.

Geben Sie den Pfad zu einem Skript (.ps1) oder einer Moduldatei (.psm1) oder zu einem Verzeichnis ein, das Skripts oder Module enthält. Wenn das Verzeichnis andere Dateitypen enthält, werden diese ignoriert.

Um Dateien zu analysieren, die sich nicht im Stammverzeichnis des angegebenen Pfads befinden, verwenden Sie ein Feldhalterzeichen (C:\Modules\MyModule\*) oder den Parameter Recurse .

Type:String
Aliases:PSPath
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:True

-Recurse

Führt Script Analyzer für die Dateien im Pfadverzeichnis und alle Unterverzeichnisse rekursiv aus.

Recurse gilt nur für den Path-Parameterwert. Verwenden Sie den Parameter RecurseCustomRulePath, um CustomRulePath rekursiv zu durchsuchen.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RecurseCustomRulePath

Fügt Regeln hinzu, die in Unterverzeichnissen des CustomRulePath-Speicherorts definiert sind. Standardmäßig werden nur die benutzerdefinierten Regeln verwendet, Invoke-ScriptAnalyzer die in der angegebenen Datei oder dem angegebenen Verzeichnis definiert sind. Verwenden Sie zum Einschließen der integrierten Regeln den IncludeDefaultRules-Parameter .

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ReportSummary

Schreiben Sie eine Zusammenfassung der festgestellten Verstöße an den Host.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SaveDscDependency

Auflösen von DSC-Ressourcenabhängigkeiten

Wenn Invoke-ScriptAnalyzer mit diesem Parameter ausgeführt wird, wird nach Instanzen von Import-DSCResource -ModuleName <somemodule>gesucht. Wenn <somemodule> nicht gefunden werden kann, indem Sie nach suchen $env:PSModulePath, Invoke-ScriptAnalyzer gibt den Analysefehler zurück. Dieser Fehler wird dadurch verursacht, dass der PowerShell-Parser das Symbol für <somemodule>nicht finden konnte.

Wenn Invoke-ScriptAnalyzer das Modul im PowerShell-Katalog gefunden wird, lädt es das fehlende Modul in einen temporären Pfad herunter. Der temporäre Pfad wird dann für die Dauer der Überprüfung hinzugefügt $env:PSModulePath . Der temporäre Speicherort befindet sich in $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ScriptDefinition

Führt die Analyse für Befehle, Funktionen oder Ausdrücke in einer Zeichenfolge aus. Sie können dieses Feature verwenden, um Anweisungen, Ausdrücke und Funktionen unabhängig vom Skriptkontext zu analysieren.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Settings

Ein Pfad zu einer Datei, die ein benutzerdefiniertes Profil oder ein Hashtabellenobjekt enthält, das Einstellungen für ScriptAnalyzer enthält.

Wird mit den Parametern und Werten ausgeführt Invoke-ScriptAnalyzer , die in der Datei oder Hashtabelle angegeben sind.

Wenn der Pfad oder der Inhalt der Datei oder Hashtabelle ungültig ist, wird er ignoriert. Die Parameter und Werte im Profil haben Vorrang vor demselben Parameter und den werten, die in der Befehlszeile angegeben sind.

Eine Script Analyzer-Profildatei ist eine Textdatei, die eine Hashtabelle mit einem oder mehreren der folgenden Schlüssel enthält:

  • CustomRulePath
  • ExcludeRules
  • IncludeDefaultRules
  • IncludeRules
  • RecurseCustomRulePath
  • Regeln
  • severity

Die Schlüssel und Werte im Profil werden so interpretiert, als wären sie Standardparameter und Werte von Invoke-ScriptAnalyzer, ähnlich wie beim Splatting. Weitere Informationen finden Sie unter about_Splatting.

Type:Object
Aliases:Profile
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Severity

Nach dem Ausführen von Script Analyzer mit allen Regeln wählt dieser Parameter Regelverstöße mit dem angegebenen Schweregrad aus.

Gültige Werte sind:

  • Fehler
  • Warnung
  • Information

Sie können einen oder mehrere Schweregradwerte angeben.

Der Parameter filtert die Regelverstöße erst nach dem Ausführen aller Regeln. Verwenden Sie zum effizienten Filtern von Regeln, Get-ScriptAnalyzerRule um die Regeln auszuwählen, die Sie ausführen möchten.

Der Schweregradparameter hat Vorrang vor IncludeRule. Wenn der Schweregrad beispielsweise lautet Error, können Sie IncludeRule nicht verwenden, um eine Warning Regel einzuschließen.

Type:String[]
Position:Named
Default value:All rule violations
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SuppressedOnly

Gibt Verstöße nur für Regeln zurück, die unterdrückt werden.

Gibt ein SuppressedRecord-Objekt zurück (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).

Verwenden Sie zum Unterdrücken einer Regel das SuppressMessageAttribute.To suppress a rule, use the SuppressMessageAttribute. Hilfe hierzu finden Sie in den Beispielen.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Zeigt, was geschieht, wenn das Cmdlet ausgeführt wird. Das Cmdlet wird nicht ausgeführt.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Eingaben

None

Eingaben können nicht an dieses Cmdlet weitergereicht werden.

Ausgaben

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Gibt standardmäßig Invoke-ScriptAnalyzer ein DiagnosticRecord-Objekt für jede Regelverletzung zurück.

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

Wenn Sie den Parameter SuppressedOnly verwenden, Invoke-ScriptAnalyzer gibt stattdessen ein SuppressedRecord-Objekt zurück.