Korzystanie z narzędzia PSScriptAnalyzer

W tym artykule opisano różne funkcje programu PSScriptAnalyzer i sposób ich używania.

Błędy parsera

Począwszy od wersji 1.18.0, PSScriptAnalyzer emituje błędy analizatora jako rekordy diagnostyczne w strumieniu wyjściowym.

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.

Parametr RuleName jest ustawiony na wartość ErrorId błędu analizatora.

Aby pominąć ParseErrors, nie dołączaj go jako wartości w parametrze Severity .

$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.

Pomijanie reguł

Regułę można pominąć, dekorując skrypt, funkcję lub parametr za pomocą . Atrybut SuppressMessageAttribute sieci NET. Konstruktor dla SuppressMessageAttribute przyjmuje dwa parametry: kategorię i identyfikator sprawdzania. Ustaw parametr categoryID na nazwę reguły, którą chcesz pominąć, a parametr checkID ustaw na wartość null lub pusty ciąg. Opcjonalnie możesz dodać trzeci nazwany parametr z uzasadnieniem pomijania komunikatu:

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

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

}

W zakresie skryptu, funkcji lub parametru, który został ozdobiony, wszystkie naruszenia reguł są pomijane.

Aby pominąć komunikat dla określonego parametru, ustaw parametr CheckId SuppressMessageAttribute na nazwę parametru:

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

Użyj właściwości ScopeSuppressMessageAttribute , aby ograniczyć pomijanie reguł do funkcji lub klas w zakresie atrybutu.

Użyj wartości Function , aby pominąć naruszenia wszystkich funkcji w zakresie atrybutu. Użyj wartości Klasa , aby pominąć naruszenia we wszystkich klasach w zakresie atrybutu:

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

function InternalFunction
{
    param()

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

Możesz dodatkowo ograniczyć tłumienie na podstawie nazwy funkcji, parametru, klasy, zmiennej lub obiektu, ustawiając właściwość Target w SuppressMessageAttribute na wyrażenie regularne lub wzorzec dziki.

Na przykład, aby pominąć naruszenie reguły PSAvoidUsingWriteHost w i start-bar ale start-baz nie w start-foo i 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"
}

Aby pominąć naruszenia we wszystkich funkcjach:

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

Aby pominąć naruszenia w start-bar, start-bazstart-bam ale nie w start-foo:

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

Uwaga / Notatka

Nie można pominąć błędów analizatora za pomocą atrybutu SuppressMessageAttribute.

Obsługa ustawień w programie ScriptAnalyzer

Możesz utworzyć ustawienia opisujące reguły ScriptAnalyzer do uwzględnienia lub wykluczenia na podstawie ważności. Użyj parametru Ustawienia , Invoke-ScriptAnalyzer aby określić konfigurację. Parametr Settings pozwala stworzyć niestandardową konfigurację dla konkretnego środowiska. ScriptAnalyzer obsługuje następujące tryby określania pliku z ustawieniami:

Wbudowane ustawienia wstępne

ScriptAnalyzer dostarcza zestaw wbudowanych ustawień wstępnych, których można używać do analizowania skryptów. Jeśli na przykład chcesz uruchomić reguły Galeria programu PowerShell w module, użyj następującego polecenia:

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

Ponadto można użyć innych wbudowanych ustawień wstępnych, w tym DSC i CodeFormatting. Te ustawienia predefiniowane można uzupełniać Tab dla parametru Ustawienia .

Wyraźny

Poniższy przykład wyklucza dwie reguły z domyślnego zestawu reguł i dowolną regułę o ważności innej niż Błąd i Ostrzeżenie.

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

Następnie możesz wywołać ten plik ustawień za pomocą Invoke-ScriptAnalyzer:

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

W następnym przykładzie wybrano kilka reguł do wykonania zamiast wszystkich reguł domyślnych.

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

Następnie możesz wywołać ten plik ustawień:

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

Niejawnie

Jeśli umieścisz plik ustawień o nazwie PSScriptAnalyzerSettings.psd1 w katalogu głównym projektu, program PSScriptAnalyzer odnajdzie go po przekazaniu katalogu głównego projektu jako parametru Path .

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

Udostępnianie ustawień ma wyraźne pierwszeństwo nad tym trybem ukrytym. Przykładowe pliki ustawień znajdziesz w folderze Settings modułu PSScriptAnalyzer .

Sprawdzanie zgodności wersji programu PowerShell

PSScriptAnalyzer może sprawdzać skrypty programu PowerShell pod kątem niezgodności z innymi wersjami i środowiskami programu PowerShell. Program PSScriptAnalyzer zawiera cztery reguły, które sprawdzają problemy ze zgodnością:

• PSUseCompatibleCmdlets sprawdza, czy polecenia cmdlet używane w skrypcie są dostępne w innych środowiskach programu PowerShell
• PSUseCompatibleCommands sprawdza, czy polecenia używane w skrypcie są dostępne w innych środowiskach programu PowerShell
• PSUseCompatibleSyntax sprawdza, czy składnia użyta w skrypcie jest kompatybilna z innymi wersjami PowerShella
• PSUseCompatibleTypes sprawdza, czy typy .NET i metody statyczne lub właściwości są dostępne w innych środowiskach programu PowerShell

Aby uzyskać więcej informacji na temat korzystania z tych reguł, zobacz Sprawdzanie zgodności wersji programu PowerShell przy użyciu PSScriptAnalyzer na blogu zespołu programu PowerShell.

Reguły niestandardowe

Istnieje możliwość podania co najmniej jednej ścieżki do reguł niestandardowych w pliku ustawień. Ważne jest, aby te ścieżki wskazywały albo folder modułu, który niejawnie używa manifestu modułu, albo do pliku skryptu modułu (.psm1). Moduł musi wyeksportować niestandardowe funkcje reguł przy użyciu Export-ModuleMember , aby były one dostępne dla PSScriptAnalyzer.

W tym przykładzie własność CustomRulePath wskazuje na dwa różne moduły. Oba moduły eksportują funkcje reguły z czasownikiem Measure , więc Measure-* jest używany dla właściwości IncludeRules.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

Reguły domyślne można również dodawać, wyświetlając je we właściwości IncludeRules . W przypadku dołączania reguł domyślnych ważne jest, aby ustawić właściwość IncludeDefaultRules na $true; w przeciwnym razie używane są reguły domyślne.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Używanie niestandardowych reguł w Visual Studio Code (VS Code)

Możesz też korzystać z niestandardowych reguł dostępnych w pliku ustawień w VS Code. Dodaj plik ustawień przestrzeni roboczej VS Code (.vscode/settings.json) z następującą zawartością.

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

ScriptAnalyzer jako biblioteka .NET

Aparat i funkcje narzędzia ScriptAnalyzer można korzystać bezpośrednio jako biblioteka.

Oto interfejsy publiczne:

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)

Korekta naruszeń

Możesz użyć przełącznika Napraw, aby automatycznie zastąpić treści powodujące naruszenia sugerowaną alternatywą. Dodatkowo, ponieważ Invoke-ScriptAnalyzer implementuje SupportsShouldProcess, możesz użyć WhatIf lub Potwierdź , aby dowiedzieć się, które poprawki zostaną zastosowane. Powinieneś używać kontroli wersji przy wprowadzaniu poprawek, ponieważ niektóre zmiany, takie jak ta w AvoidUsingPlainTextForPassword, mogą wymagać innych modyfikacji skryptów, których nie da się wprowadzić automatycznie. Początkowe kodowanie nie zawsze może zostać zachowane, gdy automatycznie stosujesz sugestie. Powinieneś sprawdzić kodowanie plików, jeśli twoje skrypty zależą od konkretnego kodowania.

Właściwość SuggestedCorrections w rekordzie błędu umożliwia szybkie poprawki w edytorach takich jak VS Code. Udostępniamy prawidłową sugerowaną poprawkę dla następujących reguł:

• Unikaj aliasu
• UnikajUżywaniaPlainTextForPassword
• Wprowadzający w błądBacktick
• MissingModuleManifestField
• UseToExportFieldsInManifest