Invoke-ScriptAnalyzer

Utvärderar ett skript eller en modul baserat på valda regler för bästa praxis

Syntax

Path_SuppressedOnly (Standard)

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

Path_IncludeSuppressed

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

ScriptDefinition_IncludeSuppressed

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

ScriptDefinition_SuppressedOnly

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 utvärderar skript eller modulfiler (.ps1, .psm1och .psd1 filer) baserat på en samling regelverksregler och returnerar objekt som representerar regelöverträdelser. Den innehåller även särskilda regler för att analysera DSC-resurser.

Invoke-ScriptAnalyzer levereras med en uppsättning inbyggda regler. Som standard används alla regler. Du kan använda parametrarna IncludeRule och ExcludeRule för att välja de regler som du vill använda. Du kan använda cmdleten Get-ScriptAnalyzerRule för att undersöka och välja de regler som du vill inkludera eller exkludera från utvärderingen.

Du kan också använda anpassade regler som du skriver i PowerShell-skript eller kompilera i sammansättningar med C#. Anpassade regler kan också väljas med parametrarna IncludeRule och ExcludeRule.

Du kan också inkludera en regel i analysen, men utelämna utdata från regeln för valda funktioner eller skript. Den här funktionen bör endast användas när det behövs. Om du vill hämta regler som har undertryckts kör du Invoke-ScriptAnalyzer med parametern SuppressedOnly.

För användning i CI-system avslutar EnableExit gränssnittet med en slutkod som motsvarar antalet felposter.

Exempel

EXEMPEL 1 – Kör alla skriptanalysregler på ett skript

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

EXEMPEL 2 – Kör alla script analyzer-regler på alla filer i katalogen Moduler

I det här exemplet körs alla Script Analyzer-regler på alla .ps1- och .psm1-filer i din användarbaserade Modules-katalog och dess underkataloger.

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

EXEMPEL 3 – Kör en enskild regel i en modul

Det här exemplet kör endast PSAvoidUsingPositionalParameters regel för filerna i mappen PSDiagnostics modul. Du kan använda ett kommando som det här för att hitta alla instanser av en viss regelöverträdelse.

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

EXEMPEL 4 – Kör alla regler utom två på dina moduler

Det här exemplet kör alla regler förutom PSAvoidUsingCmdletAliases och PSAvoidUsingInternalURLs på filerna .ps1 och .psm1 i katalogen MyModules och i dess underkataloger.

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

EXEMPEL 5 – Kör Skriptanalys med anpassade regler

Det här exemplet kör Script Analyzer på Test-Script.ps1 med standardregler och regler i den C:\CommunityAnalyzerRules sökvägen.

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

EXEMPEL 6 – Kör endast de regler som är allvarlighetsgrad för fel och som har PSDSC-källnamnet

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

EXEMPEL 7 – Förhindra regelöverträdelser

Det här exemplet visar hur du undertrycker rapporteringen av regelöverträdelser i en funktion och hur du identifierar regelöverträdelser som undertrycks.

I exemplet används attributet SuppressMessageAttribute för att utelämna PSUseSingularNouns och PSAvoidUsingCmdletAliases regler för funktionen Get-Widgets i Get-Widgets.ps1 skriptet. Du kan använda det här attributet för att utelämna en regel för en modul, ett skript, en klass, en funktion, en parameter eller en rad.

Det första kommandot kör Script Analyzer på skriptfilen som innehåller funktionen. Utdata rapporterar en regelöverträdelse. Även om fler regler överträds rapporteras ingen av de undertryckta reglerna.

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

Det andra kommandot använder parametern SuppressedOnly för att rapportera överträdelser av reglerna som ignoreras i skriptfilen.

EXEMPEL 8 – Analysera skriptfiler med hjälp av en profildefinition

I det här exemplet skapar vi en Script Analyzer-profil och sparar den i filen ScriptAnalyzerProfile.txt i den aktuella katalogen. Vi kör Invoke-ScriptAnalyzer på modulfilerna BitLocker. Värdet för parametern Profile är sökvägen till script analyzer-profilen.

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

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

Om du inkluderar en parameter i konflikt i kommandot Invoke-ScriptAnalyzer, till exempel -Severity Error, använder cmdleten profilvärdet och ignorerar parametern.

EXEMPEL 9 – Analysera ett skript som lagras som en sträng

I det här exemplet används parametern ScriptDefinition för att analysera en funktion på kommandoraden. Funktionssträngen omges av citattecken.

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

När du använder parametern ScriptDefinition är egenskapen FileName för objektet DiagnosticRecord$null.

Parametrar

-Confirm

Uppmanar dig att bekräfta innan du kör cmdleten.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False
Alias:jfr

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-CustomRulePath

Ange sökvägen till en fil som definierar regler eller en katalog som innehåller filer som definierar regler. Jokertecken stöds. När CustomRulePath- anges används endast de anpassade regler som finns i de angivna sökvägarna för analysen. Om Invoke-ScriptAnalyzer inte kan hitta regler i kör den standardreglerna utan föregående meddelande.

Om du vill lägga till regler som definierats i underkataloger för sökvägen använder du parametern RecurseCustomRulePath. Om du vill inkludera de inbyggda reglerna lägger du till parametern IncludeDefaultRules.

Parameteregenskaper

Typ:

String[]

Standardvärde:None
Stöder jokertecken:True
DontShow:False
Alias:CustomizedRulePath (på engelska)

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-EnableExit

När analysen är klar avslutar den här parametern PowerShell-sessionerna och returnerar en slutkod som är lika med antalet felposter. Detta kan vara användbart i ci-pipelinen (continuous integration).

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-ExcludeRule

Utelämnar de angivna reglerna från Script Analyzer-testet. Jokertecken stöds.

Ange en kommaavgränsad lista med regelnamn, en variabel som innehåller regelnamn eller ett kommando som hämtar regelnamn. Du kan också ange en lista över undantagna regler i en Script Analyzer-profilfil. Du kan exkludera standardregler och regler i en anpassad regelsökväg.

När du exkluderar en regel körs regeln inte på någon av filerna i sökvägen. Om du vill undanta en regel på en viss rad, parameter, funktion, skript eller klass justerar du parametern Path eller utelämnar regeln. Information om hur du utelämnar en regel finns i exemplen.

Om en regel anges i både ExcludeRule- och IncludeRule- samlingar undantas regeln.

Parameteregenskaper

Typ:

String[]

Standardvärde:All rules are included.
Stöder jokertecken:True
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-Fix

Åtgärdar vissa varningar som innehåller en korrigering i deras DiagnosticRecord.

När du använde Fixanvänder Invoke-ScriptAnalyzer korrigeringarna innan du kör analysen. Kontrollera att du har en säkerhetskopia av dina filer när du använder den här parametern. Den försöker bevara filkodningen, men det finns fortfarande vissa fall där kodningen kan ändras.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

Path_SuppressedOnly
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False
Path_IncludeSuppressed
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-IncludeDefaultRules

Anropa standardregler tillsammans med anpassade regler.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-IncludeRule

Kör endast de angivna reglerna i skriptanalystestet. PsScriptAnalyzer kör som standard alla regler.

Ange en kommaavgränsad lista med regelnamn, en variabel som innehåller regelnamn eller ett kommando som hämtar regelnamn. Jokertecken stöds. Du kan också ange regelnamn i en Script Analyzer-profilfil.

När du använder parametern CustomdRulePath kan du använda den här parametern för att inkludera standardregler och regler i sökvägarna för anpassade regler.

Om en regel anges i både ExcludeRule- och IncludeRule- samlingar undantas regeln.

Parametern allvarlighetsgrad har företräde framför IncludeRule-. Om allvarlighetsgrad är Errorkan du till exempel inte använda IncludeRule för att inkludera en Warning regel.

Parameteregenskaper

Typ:

String[]

Standardvärde:All rules are included.
Stöder jokertecken:True
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-IncludeSuppressed

Inkludera undertryckt diagnostik i utdata.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

Path_IncludeSuppressed
Position:Named
Obligatorisk:True
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False
ScriptDefinition_IncludeSuppressed
Position:Named
Obligatorisk:True
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-Path

Anger sökvägen till skripten eller modulen som ska analyseras. Jokertecken stöds.

Ange sökvägen till ett skript (.ps1) eller modulfilen (.psm1) eller till en katalog som innehåller skript eller moduler. Om katalogen innehåller andra typer av filer ignoreras de.

Om du vill analysera filer som inte finns i rotkatalogen för den angivna sökvägen använder du ett jokertecken (C:\Modules\MyModule\*) eller parametern Recurse.

Parameteregenskaper

Typ:String
Standardvärde:None
Stöder jokertecken:True
DontShow:False
Alias:PSPath

Parameteruppsättningar

Path_SuppressedOnly
Position:0
Obligatorisk:True
Värde från pipeline:True
Värde från pipeline efter egenskapsnamn:True
Värde från återstående argument:False
Path_IncludeSuppressed
Position:0
Obligatorisk:True
Värde från pipeline:True
Värde från pipeline efter egenskapsnamn:True
Värde från återstående argument:False

-Recurse

Kör Script Analyzer på filerna i katalogen Path och alla underkataloger rekursivt.

Recurse gäller endast för parametervärdet Sökväg. Om du vill söka i CustomRulePath rekursivt använder du parametern RecurseCustomRulePath.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-RecurseCustomRulePath

Lägger till regler som definierats i underkataloger för platsen CustomRulePath. Som standard använder Invoke-ScriptAnalyzer endast de anpassade regler som definierats i den angivna filen eller katalogen. Om du vill inkludera de inbyggda reglerna använder du parametern IncludeDefaultRules.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-ReportSummary

Skriv en sammanfattning av de överträdelser som hittats till värden.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-SaveDscDependency

Lös DSC-resursberoenden.

När Invoke-ScriptAnalyzer körs med den här parametern letar den efter instanser av Import-DSCResource -ModuleName <somemodule>. Om <somemodule> inte kan hittas genom att söka i $env:PSModulePathreturnerar Invoke-ScriptAnalyzer parsfel. Det här felet orsakas av att PowerShell-parsern inte kan hitta symbolen för <somemodule>.

Om Invoke-ScriptAnalyzer hittar modulen i PowerShell-galleriet laddar den ned den saknade modulen till en temporär sökväg. Den temporära sökvägen läggs sedan till i $env:PSModulePath under hela genomsökningen. Den temporära platsen finns i $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-ScriptDefinition

Kör analysen på kommandon, funktioner eller uttryck i en sträng. Du kan använda den här funktionen för att analysera instruktioner, uttryck och funktioner, oberoende av deras skriptkontext.

Parameteregenskaper

Typ:String
Standardvärde:None
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

ScriptDefinition_IncludeSuppressed
Position:0
Obligatorisk:True
Värde från pipeline:True
Värde från pipeline efter egenskapsnamn:True
Värde från återstående argument:False
ScriptDefinition_SuppressedOnly
Position:0
Obligatorisk:True
Värde från pipeline:True
Värde från pipeline efter egenskapsnamn:True
Värde från återstående argument:False

-Settings

En sökväg till en fil som innehåller en användardefinierad profil eller ett hashtable-objekt som innehåller inställningar för ScriptAnalyzer.

Kör Invoke-ScriptAnalyzer med de parametrar och värden som anges i filen eller hashtable.

Om sökvägen eller innehållet i filen eller hashtabellen är ogiltigt ignoreras den. Parametrarna och värdena i profilen har företräde framför samma parameter och värden som anges på kommandoraden.

En Script Analyzer-profilfil är en textfil som innehåller en hashtable med en eller flera av följande nycklar:

  • CustomRulePath
  • ExcludeRules
  • IncludeDefaultRules
  • IncludeRules
  • RecurseCustomRulePath
  • Reglemente
  • Svårighetsgrad

Nycklarna och värdena i profilen tolkas som om de vore standardparametrar och värden för Invoke-ScriptAnalyzer, liknande splatting. Mer information finns i about_Splatting.

Parameteregenskaper

Typ:Object
Standardvärde:None
Stöder jokertecken:False
DontShow:False
Alias:Profil

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-Severity

När du har kört Script Analyzer med alla regler väljer den här parametern regelöverträdelser med angiven allvarlighetsgrad.

Giltiga värden är:

  • Fel
  • Varning
  • Information.

Du kan ange en eller flera allvarlighetsgradsvärden.

Parametern filtrerar regelöverträdelserna först när alla regler har körts. Om du vill filtrera regler effektivt använder du Get-ScriptAnalyzerRule för att välja de regler som du vill köra.

Parametern allvarlighetsgrad har företräde framför IncludeRule-. Om allvarlighetsgrad är Errorkan du till exempel inte använda IncludeRule för att inkludera en Warning regel.

Parameteregenskaper

Typ:

String[]

Standardvärde:All rule violations
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-SuppressedOnly

Returnerar endast överträdelser för regler som ignoreras.

Returnerar ett SuppressedRecord -objekt (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).

Om du vill förhindra en regel använder du SuppressMessageAttribute. Mer information finns i exemplen.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False

Parameteruppsättningar

Path_SuppressedOnly
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False
ScriptDefinition_SuppressedOnly
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

-WhatIf

Visar vad som skulle hända om kommandot körs. Cmdleten körs inte.

Parameteregenskaper

Typ:SwitchParameter
Standardvärde:False
Stöder jokertecken:False
DontShow:False
Alias:Wi

Parameteruppsättningar

(All)
Position:Named
Obligatorisk:False
Värde från pipeline:False
Värde från pipeline efter egenskapsnamn:False
Värde från återstående argument:False

CommonParameters

Den här cmdleten stöder vanliga parametrar: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction och -WarningVariable. Mer information finns i about_CommonParameters.

Indata

None

Du kan inte skicka indata till den här cmdleten.

Utdata

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Som standard returnerar Invoke-ScriptAnalyzer ett DiagnosticRecord- objekt för varje regelöverträdelse.

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

Om du använder parametern SuppressedOnly returnerar Invoke-ScriptAnalyzer i stället ett SuppressedRecord objekt.