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.