PSScriptAnalyzer gebruiken

In dit artikel worden de verschillende functies van PSScriptAnalyzer beschreven en hoe u deze kunt gebruiken.

Parser fouten

Vanaf versie 1.18.0 verzendt PSScriptAnalyzer parserfouten als diagnostische records in de uitvoerstroom.

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.

De RuleName is ingesteld op de ErrorId van de parserfout.

Als u ParseErrors wilt onderdrukken, neemt u deze niet op als een waarde in de parameter Ernst .

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

Regels onderdrukken

U kunt een regel onderdrukken door een script, functie of parameter te versieren met . SuppressMessageAttribute van NET. De constructor voor SuppressMessageAttribute heeft twee parameters nodig: een categorie en een controle-ID. Stel de parameter categoryID in op de naam van de regel die u wilt onderdrukken en stel de checkID-parameter in op een null of lege tekenreeks. U kunt optioneel een derde benoemde parameter toevoegen met een rechtvaardiging voor het onderdrukken van het bericht:

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

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

}

Binnen het bereik van het script, de functie of de parameter die u hebt versierd, worden alle regelovertredingen onderdrukt.

Als u een bericht op een specifieke parameter wilt onderdrukken, stelt u de parameter CheckId van SuppressMessageAttribute in op de naam van de parameter:

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

Gebruik de eigenschap Bereik van SuppressMessageAttribute om het onderdrukken van regels te beperken tot functies of klassen binnen het bereik van het kenmerk.

Gebruik de waarde Functie om schendingen te onderdrukken voor alle functies binnen het bereik van het kenmerk. Gebruik de waarde Class om schendingen te onderdrukken voor alle klassen binnen het bereik van het kenmerk:

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

function InternalFunction
{
    param()

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

Je kunt suppression verder beperken op basis van de naam van een functie, parameter, klasse, variabele of object door de Target-eigenschap van SuppressMessageAttribute in te stellen op een reguliere expressie of een wildcardpatroon.

Als u bijvoorbeeld de schending van de PSAvoidUsingWriteHost-regel wilt onderdrukken in start-bar en start-baz maar niet in start-foo en 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"
}

Overtredingen in alle functies onderdrukken:

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

Om overtredingen te onderdrukken in start-bar, start-baz en start-bam maar niet in start-foo:

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

Ondersteuning voor instellingen in ScriptAnalyzer

U kunt instellingen maken die de ScriptAnalyzer-regels beschrijven die moeten worden opgenomen of uitgesloten op basis van ernst. Gebruik de parameter Instellingen van Invoke-ScriptAnalyzer om de configuratie op te geven. De instellingen-parameter stelt je in staat een aangepaste configuratie te maken voor een specifieke omgeving. ScriptAnalyzer ondersteunt de volgende modi voor het specificeren van het instellingenbestand:

Ingebouwde voorinstellingen

ScriptAnalyzer levert een set ingebouwde voorinstellingen die kunnen worden gebruikt om scripts te analyseren. Als u bijvoorbeeld PowerShell Gallery-regels wilt uitvoeren op uw module, gebruikt u de volgende opdracht:

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

Daarnaast kunt u andere ingebouwde voorinstellingen gebruiken, waaronder DSC en CodeFormatting. Deze voorinstellingen kunnen met het tabblad worden ingevuld voor de parameter Instellingen .

Uitdrukkelijk

In het volgende voorbeeld worden twee regels uitgesloten van de standaardset regels en elke regel met een andere ernst dan Fout en Waarschuwing.

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

U kunt dat instellingenbestand dan aanroepen met Invoke-ScriptAnalyzer:

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

In het volgende voorbeeld worden enkele regels geselecteerd die moeten worden uitgevoerd in plaats van alle standaardregels.

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

U kunt dan dat instellingenbestand aanroepen:

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

Impliciet

Als u een instellingenbestand met de naam PSScriptAnalyzerSettings.psd1 in de hoofdmap van uw project plaatst, wordt dit door PSScriptAnalyzer gedetecteerd wanneer u de hoofdmap van het project doorgeeft als de parameter Pad .

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

Het expliciet geven van instellingen heeft een hogere prioriteit dan deze impliciete modus. Je kunt voorbeeldinstellingen vinden in de Settings map van de PSScriptAnalyzer-module .

Controleer de compatibiliteit van de PowerShell-versie

PSScriptAnalyzer kan PowerShell-scripts controleren op incompatibiliteit met andere PowerShell-versies en -omgevingen. PSScriptAnalyzer bevat vier regels die controleren op compatibiliteitsproblemen:

• PSUseCompatibleCmdlets controleert of cmdlets die in een script worden gebruikt, beschikbaar zijn in andere PowerShell-omgevingen
• PSUseCompatibleCommands controleert of opdrachten die in een script worden gebruikt, beschikbaar zijn in andere PowerShell-omgevingen
• PSUseCompatibleSyntax controleert of een syntaxis die in een script wordt gebruikt compatibel is met andere versies van PowerShell
• PSUseCompatibleTypes controleert of .NET-typen en statische methoden of eigenschappen beschikbaar zijn in andere PowerShell-omgevingen

Zie PSScriptAnalyzer gebruiken om de compatibiliteit van de PowerShell-versie te controleren op de PowerShell Team-blog voor meer informatie over het gebruik van deze regels.

Aangepaste regels

Het is mogelijk om een of meer paden naar aangepaste regels op te geven in het instellingenbestand. Het is belangrijk dat deze paden verwijzen naar de map van een module, die impliciet gebruikmaakt van het modulemanifest, of naar het scriptbestand van de module (.psm1). De module moet de aangepaste regelfuncties exporteren om Export-ModuleMember beschikbaar te zijn voor PSScriptAnalyzer.

In dit voorbeeld wijst de eigenschap CustomRulePath naar twee verschillende modules. Beide modules exporteren de regelfuncties met het werkwoord Measure en worden Measure-* dus gebruikt voor de eigenschap IncludeRules.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

U kunt ook standaardregels toevoegen door de regels op te geven in de eigenschap IncludeRules . Wanneer u standaardregels opneemt, is het belangrijk dat u de eigenschap IncludeDefaultRules instelt op $true; anders worden de standaardregels gebruikt.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Aangepaste regels gebruiken in Visual Studio Code (VS Code)

Je kunt ook de aangepaste regels gebruiken die in het instellingenbestand in VS Code staan. Voeg een VS Code-werkruimteinstellingenbestand toe (.vscode/settings.json) met de volgende inhoud.

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

ScriptAnalyzer als een .NET-bibliotheek

U kunt de engine en functionaliteit van ScriptAnalyzer rechtstreeks als een bibliotheek gebruiken.

Dit zijn de openbare interfaces:

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)

Overtreding correctie

Je kunt de Fix-schakelaar gebruiken om automatisch overtredingveroorzakende inhoud te vervangen door een voorgestelde alternatief. Omdat Invoke-ScriptAnalyzerSupportsShouldProcess implementeert, kunt u bovendien WhatIf of Confirm gebruiken om erachter te komen welke correcties zouden worden toegepast. Je zou broncode moeten gebruiken bij het toepassen van correcties, want sommige wijzigingen, zoals die voor AvoidUsingPlainTextForPassword, kunnen andere scriptwijzigingen vereisen die niet automatisch kunnen worden doorgevoerd. Initiële codering kan niet altijd behouden blijven als je automatisch suggesties toepast. Je moet de bestandscodering controleren als je scripts afhankelijk zijn van een bepaalde codering.

De eigenschap SuggestedCorrections van het foutrecord maakt quick-fix scenario's mogelijk in editors zoals VS Code. We bieden geldige SuggestedCorrection voor de volgende regels:

• VermijdenAlias
• AvoidUsingPlainTextForPassword
• Misleidende backtick
• OntbrekendeModuleManifestveld
• UseToExportFieldsInManifest