Invoke-ScriptAnalyzer

Referentie

Module:: PSScriptAnalyzer

Evalueert een script of module op basis van geselecteerde regels voor aanbevolen procedures

Syntaxis

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>]

Description

Invoke-ScriptAnalyzer evalueert scripts of modulebestanden (.ps1, .psm1en .psd1 bestanden) op basis van een verzameling best practice-regels en retourneert objecten die regelschendingen vertegenwoordigen. Het bevat ook speciale regels voor het analyseren van DSC-resources.

Invoke-ScriptAnalyzer wordt geleverd met een set ingebouwde regels. Standaard worden alle regels gebruikt. U kunt de parameters IncludeRule en ExcludeRule gebruiken om de gewenste regels te selecteren. U kunt de cmdlet Get-ScriptAnalyzerRule gebruiken om de regels te onderzoeken en te selecteren die u wilt opnemen of uitsluiten van de evaluatie.

U kunt ook aangepaste regels gebruiken die u schrijft in PowerShell-scripts of compileren in assembly's met behulp van C#. Aangepaste regels kunnen ook worden geselecteerd met de parameters IncludeRule en ExcludeRule.

U kunt ook een regel opnemen in de analyse, maar de uitvoer van die regel onderdrukken voor geselecteerde functies of scripts. Deze functie mag alleen worden gebruikt wanneer dat nodig is. Als u regels wilt ophalen die zijn onderdrukt, voert u Invoke-ScriptAnalyzer uit met de parameter SuppressedOnly.

Voor gebruik in CI-systemen sluit de EnableExit- de shell af met een afsluitcode die gelijk is aan het aantal foutrecords.

Voorbeelden

VOORBEELD 1: alle Script Analyzer-regels uitvoeren op een script

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

VOORBEELD 2: alle Script Analyzer-regels uitvoeren op alle bestanden in de map Modules

In dit voorbeeld worden alle Script Analyzer-regels uitgevoerd op alle .ps1- en .psm1 bestanden in uw Modules map en de bijbehorende submappen.

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

VOORBEELD 3: één regel uitvoeren op een module

In dit voorbeeld wordt alleen de regel PSAvoidUsingPositionalParameters uitgevoerd op de bestanden in de map PSDiagnostics module. U kunt een dergelijke opdracht gebruiken om alle exemplaren van een bepaalde regelschending te vinden.

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

VOORBEELD 4: alle regels uitvoeren, behalve twee regels op uw modules

In dit voorbeeld worden alle regels uitgevoerd, met uitzondering van PSAvoidUsingCmdletAliases en PSAvoidUsingInternalURLs op de bestanden .ps1 en .psm1 in de map MyModules en in de submappen.

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

VOORBEELD 5: Script Analyzer uitvoeren met aangepaste regels

In dit voorbeeld wordt Script Analyzer uitgevoerd op Test-Script.ps1 met de standaardregels en regels in het C:\CommunityAnalyzerRules pad.

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

VOORBEELD 6: voer alleen de regels uit die de ernst van de fout zijn en de naam van de PSDSC-bron hebben

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

VOORBEELD 7: schendingen van regels onderdrukken

In dit voorbeeld ziet u hoe u de rapportage van regelschendingen in een functie onderdrukt en hoe u regelschendingen detecteert die worden onderdrukt.

In het voorbeeld wordt het kenmerk SuppressMessageAttribute gebruikt om de PSUseSingularNouns- te onderdrukken en PSAvoidUsingCmdletAliases-regels voor de Get-Widgets-functie in het Get-Widgets.ps1 script. U kunt dit kenmerk gebruiken om een regel voor een module, script, klasse, functie, parameter of regel te onderdrukken.

Met de eerste opdracht wordt Script Analyzer uitgevoerd op het scriptbestand met de functie. In de uitvoer wordt een schending van een regel gerapporteerd. Hoewel er meer regels worden geschonden, wordt geen van beide onderdrukte regels gerapporteerd.

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

De tweede opdracht maakt gebruik van de parameter SuppressedOnly om schendingen van de regels te melden die zijn onderdrukt scriptbestand.

VOORBEELD 8: Scriptbestanden analyseren met behulp van een profieldefinitie

In dit voorbeeld maken we een Script Analyzer-profiel en slaan we het op in het ScriptAnalyzerProfile.txt-bestand in de huidige map. We voeren Invoke-ScriptAnalyzer uit op de modulebestanden BitLocker. De waarde van de parameter Profile is het pad naar het Script Analyzer-profiel.

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

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

Als u een conflicterende parameter opneemt in de opdracht Invoke-ScriptAnalyzer, zoals -Severity Error, gebruikt de cmdlet de profielwaarde en negeert de parameter.

VOORBEELD 9: Een script analyseren dat is opgeslagen als een tekenreeks

In dit voorbeeld wordt de parameter ScriptDefinition gebruikt om een functie op de opdrachtregel te analyseren. De functietekenreeks staat tussen aanhalingstekens.

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

Wanneer u de parameter ScriptDefinition gebruikt, wordt de eigenschap FileName van het DiagnosticRecord-object $null.

Parameters

-Confirm

U wordt gevraagd om bevestiging voordat u de cmdlet uitvoert.

Type:	SwitchParameter
Aliassen:	cf
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-CustomRulePath

Voer het pad naar een bestand in dat regels of een map definieert die bestanden bevat die regels definiëren. Jokertekens worden ondersteund. Wanneer CustomRulePath- is opgegeven, worden alleen de aangepaste regels in de opgegeven paden gebruikt voor de analyse. Als Invoke-ScriptAnalyzer geen regels in het bestand kunt vinden, worden de standaardregels zonder kennisgeving uitgevoerd.

Als u regels wilt toevoegen die zijn gedefinieerd in submappen van het pad, gebruikt u de parameter RecurseCustomRulePath. Als u de ingebouwde regels wilt opnemen, voegt u de parameter IncludeDefaultRules toe.

Type:	String[]
Aliassen:	CustomizedRulePath
Position:	Named
Default value:	None
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	True

-EnableExit

Na voltooiing van de analyse sluit deze parameter de PowerShell-sessies af en retourneert een afsluitcode die gelijk is aan het aantal foutrecords. Dit kan handig zijn in ci-pijplijn (continue integratie).

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-ExcludeRule

Hiermee worden de opgegeven regels uit de Script Analyzer-test weggelaten. Jokertekens worden ondersteund.

Voer een door komma's gescheiden lijst met regelnamen in, een variabele die regelnamen bevat of een opdracht waarmee regelnamen worden ophaalt. U kunt ook een lijst met uitgesloten regels opgeven in een Script Analyzer-profielbestand. U kunt standaardregels en regels uitsluiten in een aangepast regelpad.

Wanneer u een regel uitsluit, wordt de regel niet uitgevoerd op een van de bestanden in het pad. Als u een regel wilt uitsluiten op een bepaalde regel, parameter, functie, script of klasse, past u de parameter Path aan of onderdrukt u de regel. Zie de voorbeelden voor informatie over het onderdrukken van een regel.

Als een regel is opgegeven in zowel de ExcludeRule als IncludeRule verzamelingen, wordt de regel uitgesloten.

Type:	String[]
Position:	Named
Default value:	All rules are included.
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	True

-Fix

Hiermee worden bepaalde waarschuwingen opgelost die een oplossing bevatten in hun DiagnosticRecord.

Wanneer u Fixhebt gebruikt, past Invoke-ScriptAnalyzer de fixes toe voordat u de analyse uitvoert. Zorg ervoor dat u een back-up van uw bestanden hebt wanneer u deze parameter gebruikt. Het probeert de bestandscodering te behouden, maar er zijn nog steeds enkele gevallen waarin de codering kan worden gewijzigd.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-IncludeDefaultRules

Standaardregels aanroepen, samen met aangepaste regels.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-IncludeRule

Hiermee worden alleen de opgegeven regels in de Script Analyzer-test uitgevoerd. PsScriptAnalyzer voert standaard alle regels uit.

Voer een door komma's gescheiden lijst met regelnamen in, een variabele die regelnamen bevat of een opdracht waarmee regelnamen worden ophaalt. Jokertekens worden ondersteund. U kunt ook regelnamen opgeven in een Script Analyzer-profielbestand.

Wanneer u de parameter CustomizedRulePath gebruikt, kunt u deze parameter gebruiken om standaardregels en regels op te nemen in de aangepaste regelpaden.

Als een regel is opgegeven in zowel de ExcludeRule als IncludeRule verzamelingen, wordt de regel uitgesloten.

De parameter Ernst heeft voorrang op IncludeRule-. Als Ernst bijvoorbeeld Erroris, kunt u IncludeRule- niet gebruiken om een Warning regel op te nemen.

Type:	String[]
Position:	Named
Default value:	All rules are included.
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	True

-IncludeSuppressed

Neem onderdrukte diagnostische gegevens op in de uitvoer.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	True
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-Path

Hiermee geeft u het pad naar de scripts of module die moeten worden geanalyseerd. Jokertekens worden ondersteund.

Voer het pad in naar een script (.ps1) of modulebestand (.psm1) of naar een map die scripts of modules bevat. Als de map andere typen bestanden bevat, worden ze genegeerd.

Als u bestanden wilt analyseren die zich niet in de hoofdmap van het opgegeven pad bevinden, gebruikt u een jokerteken (C:\Modules\MyModule\*) of de parameter Recurse.

Type:	String
Aliassen:	PSPath
Position:	0
Default value:	None
Vereist:	True
Pijplijninvoer accepteren:	True
Jokertekens accepteren:	True

-Recurse

Script Analyzer wordt uitgevoerd op de bestanden in de Pad map en alle submappen recursief.

Recurse is alleen van toepassing op de parameterwaarde Path. Als u de CustomRulePath recursief wilt doorzoeken, gebruikt u de parameter RecurseCustomRulePath.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-RecurseCustomRulePath

Hiermee voegt u regels toe die zijn gedefinieerd in submappen van de CustomRulePath locatie. Standaard gebruikt Invoke-ScriptAnalyzer alleen de aangepaste regels die zijn gedefinieerd in het opgegeven bestand of de opgegeven map. Als u de ingebouwde regels wilt opnemen, gebruikt u de parameter IncludeDefaultRules.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-ReportSummary

Schrijf een samenvatting van de schendingen die aan de host zijn gevonden.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-SaveDscDependency

Dsc-resourceafhankelijkheden oplossen.

Wanneer Invoke-ScriptAnalyzer wordt uitgevoerd met deze parameter, wordt gezocht naar exemplaren van Import-DSCResource -ModuleName <somemodule>. Als <somemodule> niet kan worden gevonden door de $env:PSModulePathte doorzoeken, retourneert Invoke-ScriptAnalyzer parseringsfout. Deze fout wordt veroorzaakt doordat de PowerShell-parser het symbool voor <somemodule>niet kan vinden.

Als Invoke-ScriptAnalyzer de module vindt in de PowerShell Gallery, wordt de ontbrekende module gedownload naar een tijdelijk pad. Het tijdelijke pad wordt vervolgens toegevoegd aan $env:PSModulePath voor de duur van de scan. De tijdelijke locatie is te vinden in $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-ScriptDefinition

Hiermee wordt de analyse uitgevoerd op opdrachten, functies of expressies in een tekenreeks. U kunt deze functie gebruiken om instructies, expressies en functies te analyseren, onafhankelijk van hun scriptcontext.

Type:	String
Position:	0
Default value:	None
Vereist:	True
Pijplijninvoer accepteren:	True
Jokertekens accepteren:	False

-Settings

Een pad naar een bestand met een door de gebruiker gedefinieerd profiel of een hashtabelobject met instellingen voor ScriptAnalyzer.

Wordt Invoke-ScriptAnalyzer uitgevoerd met de parameters en waarden die zijn opgegeven in het bestand of de hashtabel.

Als het pad of de inhoud van het bestand of de hashtabel ongeldig is, wordt het genegeerd. De parameters en waarden in het profiel hebben voorrang op dezelfde parameter en waarden die zijn opgegeven op de opdrachtregel.

Een Script Analyzer-profielbestand is een tekstbestand dat een hashtabel bevat met een of meer van de volgende sleutels:

CustomRulePath
ExcludeRules
IncludeDefaultRules
IncludeRules
RecurseCustomRulePath
Reglement
Strengheid

De sleutels en waarden in het profiel worden geïnterpreteerd als standaardparameters en -waarden van Invoke-ScriptAnalyzer, vergelijkbaar met splatting. Zie about_Splattingvoor meer informatie.

Type:	Object
Aliassen:	Profile
Position:	Named
Default value:	None
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-Severity

Nadat Script Analyzer met alle regels is uitgevoerd, selecteert deze parameter regelschendingen met de opgegeven ernst.

Geldige waarden zijn:

Fout
Waarschuwing
Informatie.

U kunt een of meer ernstwaarden opgeven.

De parameter filtert de schendingen van de regels pas nadat alle regels zijn uitgevoerd. Als u regels efficiënt wilt filteren, gebruikt u Get-ScriptAnalyzerRule om de regels te selecteren die u wilt uitvoeren.

De parameter Ernst heeft voorrang op IncludeRule-. Als Ernst bijvoorbeeld Erroris, kunt u IncludeRule- niet gebruiken om een Warning regel op te nemen.

Type:	String[]
Position:	Named
Default value:	All rule violations
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-SuppressedOnly

Retourneert alleen schendingen voor regels die worden onderdrukt.

Hiermee wordt een SuppressedRecord-object geretourneerd (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).

Als u een regel wilt onderdrukken, gebruikt u de SuppressMessageAttribute-. Zie de voorbeelden voor hulp.

Type:	SwitchParameter
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

-WhatIf

Toont wat er zou gebeuren als de cmdlet wordt uitgevoerd. De cmdlet wordt niet uitgevoerd.

Type:	SwitchParameter
Aliassen:	wi
Position:	Named
Default value:	False
Vereist:	False
Pijplijninvoer accepteren:	False
Jokertekens accepteren:	False

Invoerwaarden

None

U kunt invoer voor deze cmdlet niet doorsluisen.

Uitvoerwaarden

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Standaard retourneert Invoke-ScriptAnalyzer één DiagnosticRecord-object voor elke regelschending.

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

Als u de parameter SuppressedOnly gebruikt, retourneert Invoke-ScriptAnalyzer in plaats daarvan een SuppressedRecord-objecten.

Delen via

Invoke-ScriptAnalyzer

Syntaxis

Description

Voorbeelden

VOORBEELD 1: alle Script Analyzer-regels uitvoeren op een script

VOORBEELD 2: alle Script Analyzer-regels uitvoeren op alle bestanden in de map Modules

VOORBEELD 3: één regel uitvoeren op een module

VOORBEELD 4: alle regels uitvoeren, behalve twee regels op uw modules

VOORBEELD 5: Script Analyzer uitvoeren met aangepaste regels

VOORBEELD 6: voer alleen de regels uit die de ernst van de fout zijn en de naam van de PSDSC-bron hebben

VOORBEELD 7: schendingen van regels onderdrukken

VOORBEELD 8: Scriptbestanden analyseren met behulp van een profieldefinitie

VOORBEELD 9: Een script analyseren dat is opgeslagen als een tekenreeks

Parameters

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Invoerwaarden

Uitvoerwaarden

Aanvullende resources

Delen via

Invoke-ScriptAnalyzer

Syntaxis

Description

Voorbeelden

VOORBEELD 1: alle Script Analyzer-regels uitvoeren op een script

VOORBEELD 2: alle Script Analyzer-regels uitvoeren op alle bestanden in de map Modules

VOORBEELD 3: één regel uitvoeren op een module

VOORBEELD 4: alle regels uitvoeren, behalve twee regels op uw modules

VOORBEELD 5: Script Analyzer uitvoeren met aangepaste regels

VOORBEELD 6: voer alleen de regels uit die de ernst van de fout zijn en de naam van de PSDSC-bron hebben

VOORBEELD 7: schendingen van regels onderdrukken

VOORBEELD 8: Scriptbestanden analyseren met behulp van een profieldefinitie

VOORBEELD 9: Een script analyseren dat is opgeslagen als een tekenreeks

Parameters

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Invoerwaarden

Uitvoerwaarden

Verwante koppelingen

Aanvullende resources