A PSScriptAnalyzer használata

Ez a cikk a PSScriptAnalyzer különböző funkcióit és azok használatát ismerteti.

Elemző hibák

Az 1.18.0-s verziótól kezdődően a PSScriptAnalyzer elemző hibákat bocsát ki diagnosztikai rekordként a kimeneti streamben.

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.

A RuleName az elemzőhiba ErrorId értékére van állítva.

A ParseErrors letiltásához ne foglalja bele értékként a Severity paraméterbe.

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

Szabályok elnyomása

A szabály letiltásához dekoráljon egy parancsfájlt, függvényt vagy paramétert a következővel: . NET SuppressMessageAttribute. A konstruktor SuppressMessageAttribute két paramétert vesz fel: egy kategóriát és egy ellenőrző azonosítót. Állítsa a categoryID paramétert a letiltani kívánt szabály nevére, és állítsa a checkID paramétert null vagy üres sztringre. Igény szerint hozzáadhat egy harmadik elnevezett paramétert az üzenet letiltásának indoklásával:

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

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

}

A dekorált szkript, függvény vagy paraméter hatókörében a rendszer minden szabálysértést letilt.

Ha egy adott paraméteren le szeretne tiltani egy üzenetet, állítsa a CheckId SuppressMessageAttribute paraméterét a paraméter nevére:

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

A Scope Commandtulajdonságával korlátozhatja a szabály mellőzését az attribútum hatókörén belüli függvényekre vagy osztályokra.

A Function értékkel letilthatja az attribútum hatókörébe tartozó összes függvény szabálysértéseit. Az Osztály értékkel letilthatja az attribútum hatókörébe tartozó összes osztály szabálysértéseit:

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

function InternalFunction
{
    param()

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

További korlátozásokat lehet korlátozni egy függvény, paraméter, osztály, változó vagy objektum neve alapján, ha a SuppressMessageAttributeTarget tulajdonságát reguláris kifejezésre vagy wildcard mintára állítod.

Ha például le szeretné tiltani a PSAvoidUsingWriteHost szabálysértést a start-bar és de start-baz nem a start-foo és :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"
}

Az összes funkció megsértésének elnyomása:

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

A szabálysértések elnyomása a következőbenstart-bar: start-bazstart-bamstart-foo

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

Beállítások támogatása a ScriptAnalyzerben

Létrehozhat olyan beállításokat, amelyek leírják a súlyosság alapján belefoglalni vagy kizárni kívánt ScriptAnalyzer-szabályokat. A konfiguráció megadásához használja a Beállítások paramétert Invoke-ScriptAnalyzer . A Beállítások paraméter lehetővé teszi, hogy egyedi konfigurációt hozzon létre egy adott környezethez. A ScriptAnalyzer támogatja a következő módokat a beállítások fájl megadásához:

Beépített előbeállítások

A ScriptAnalyzer beépített készleteket szállít, amelyek a szkriptek elemzésére használhatók. Ha például PowerShell-galéria szabályokat szeretne futtatni a modulon, használja a következő parancsot:

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

Emellett más beépített készleteket is használhat, például a DSC-t és a CodeFormattingot. Ezek a készletek a Beállítások paraméterhez tabulátorral is kitölthetők.

Világos

Az alábbi példa kizár két szabályt az alapértelmezett szabálykészletből, valamint a Hibaés figyelmeztetés súlyosságtól eltérő szabályt.

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

Ezután meghívhatja ezt a beállítási fájlt a következővel Invoke-ScriptAnalyzer:

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

A következő példa néhány végrehajtandó szabályt választ ki az összes alapértelmezett szabály helyett.

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

Ezután meghívhatja ezt a beállításfájlt:

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

Magától értetődő

Ha a projekt gyökerében elhelyez egy beállításfájlt PSScriptAnalyzerSettings.psd1 , a PSScriptAnalyzer felderíti azt, amikor a projekt gyökerét adja át Path paraméterként.

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

A beállítások megadása kifejezetten fontosabb a prioritás, mint ez az implicit mód. A mintabeállítások fájlokat a SettingsPSScriptAnalyzer modul mappájában találhatod.

A PowerShell-verzió kompatibilitásának ellenőrzése

A PSScriptAnalyzer képes ellenőrizni a PowerShell-szkriptek inkompatibilitását más PowerShell-verziókkal és -környezetekkel. A PSScriptAnalyzer négy szabályt tartalmaz, amelyek ellenőrzik a kompatibilitási problémákat:

• PSUseCompatibleCmdlets ellenőrzi, hogy a szkriptben használt parancsmagok elérhetők-e más PowerShell-környezetekben
• PSUseCompatibleCommands ellenőrzi, hogy a szkriptben használt parancsok elérhetők-e más PowerShell-környezetekben
• A PSUseCompatibleSyntax ellenőrzi, hogy egy szkriptben használt szintaxis kompatibilis-e más PowerShell verziókkal
• PSUseCompatibleTypes ellenőrzi, hogy a .NET típusok és statikus metódusok vagy tulajdonságok elérhetők-e más PowerShell-környezetekben

További információ a szabályok használatáról: A PowerShell-verzió kompatibilitásának ellenőrzése a PSScriptAnalyzer használatával a PowerShell-csapat blogján.

Egyéni szabályok

A beállításfájlban egy vagy több egyéni szabály elérési útját is megadhatja. Fontos, hogy ezek az elérési utak vagy egy modul mappájára mutassanak, amely implicit módon használja a moduljegyzéket, vagy a modul szkriptfájljára ()..psm1 A modulnak exportálnia kell az egyéni szabályfüggvényeket Export-ModuleMember , hogy elérhetők legyenek a PSScriptAnalyzer számára.

Ebben a példában a CustomRulePath tulajdonság két különböző modulra mutat. Mindkét modul exportálja a szabályfüggvényeket a Measure igével, így Measure-* az IncludeRules tulajdonsághoz használatos.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

Alapértelmezett szabályokat úgy is hozzáadhat, hogy listázza a szabályokat az IncludeRules tulajdonságban. Alapértelmezett szabályok megadásakor fontos, hogy az IncludeDefaultRules tulajdonságot a következőre állítsa be $true: ellenkező esetben a rendszer az alapértelmezett szabályokat használja.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Egyedi szabályok használata a Visual Studio Code-ban (VS Code)

Használhatod a VS Code beállításaiban található egyedi szabályokat is. Hozzáadj egy VS Code munkaterületi beállítási fájlt (.vscode/settings.json) az alábbi tartalommal.

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

A ScriptAnalyzer .NET könyvtárként

A ScriptAnalyzer motorját és funkcióit közvetlenül használhatja kódtárként.

Íme a nyilvános felületek:

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)

Szabálysértés javítása

A Fix kapcsolóval automatikusan helyettesítheted a szabálysértést okozó tartalmat egy javasolt alternatívára. Továbbá, mivel Invoke-ScriptAnalyzer implementálja a SupportsShouldProcess implementációt, a WhatIf vagy a Confirm használatával megtudhatja, hogy mely javításokat alkalmazza a rendszer. A javítások alkalmazásához használj forrásvezérlőt, mert bizonyos változtatások, például az AvoidUsingPlainTextForPassword esetében, más szkriptmódosításokat is igényelhetnek, amelyeket nem lehet automatikusan elvégezni. Az eredeti kódolás nem mindig marad meg, ha automatikusan alkalmazod a javaslatokat. Ellenőrizd kell a fájlkódolást, ha a szkriptek egy adott kódolástól függnek.

A hibarekord SuggestedCorrections tulajdonsága gyors javítási forgatókönyveket tesz lehetővé szerkesztőkben, például a VS Code-ban. A következő szabályokhoz biztosítunk érvényes SuggestedCorrection-t :

• Kerülje az Alias-t
• Kerülje a PlainTextForPassword használatát
• FélrevezetőBacktick
• MissingModuleManifestField
• UseToExportFieldsInManifest