Invoke-ScriptAnalyzer

Reference

Modul:: PSScriptAnalyzer

Vyhodnotí skript nebo modul na základě vybraných pravidel osvědčených postupů.

Syntaxe

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 vyhodnocuje skripty nebo soubory modulů (.ps1, .psm1a .psd1 soubory) na základě kolekce pravidel osvědčených postupů a vrací objekty, které představují porušení pravidel. Obsahuje také speciální pravidla pro analýzu prostředků DSC.

Invoke-ScriptAnalyzer se dodává se sadou předdefinovaných pravidel. Ve výchozím nastavení používá všechna pravidla. Pomocí parametrů IncludeRule a ExcludeRule můžete vybrat požadovaná pravidla. Pomocí rutiny Get-ScriptAnalyzerRule můžete prozkoumat a vybrat pravidla, která chcete zahrnout nebo vyloučit z vyhodnocení.

Můžete také použít přizpůsobená pravidla, která píšete ve skriptech PowerShellu, nebo kompilovat v sestaveních pomocí jazyka C#. Vlastní pravidla je také možné vybrat pomocí parametrů IncludeRule a ExcludeRule .

Do analýzy můžete také zahrnout pravidlo, ale potlačit jeho výstup pro vybrané funkce nebo skripty. Tato funkce by se měla používat jenom v případě potřeby. Pokud chcete získat pravidla, která byla potlačena, spusťte Invoke-ScriptAnalyzer příkaz s parametrem SuppressedOnly .

Pro použití v systémech CI EnableExit ukončí prostředí s ukončovacím kódem, který se rovná počtu záznamů o chybách.

Příklady

PŘÍKLAD 1 – Spuštění všech pravidel Analyzátoru skriptů ve skriptu

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

PŘÍKLAD 2 – Spuštění všech pravidel Analyzátoru skriptů pro všechny soubory v adresáři Modules

Tento příklad spustí všechna pravidla Analyzátoru skriptů pro všechny .ps1 soubory a .psm1 v adresáři založeném na Modules uživateli a v jeho podadresářích.

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

PŘÍKLAD 3 – Spuštění jednoho pravidla pro modul

Tento příklad spustí pouze pravidlo PSAvoidUsingPositionalParameters pro soubory ve PSDiagnostics složce modulu. Podobný příkaz můžete použít k vyhledání všech instancí porušení konkrétního pravidla.

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

PŘÍKLAD 4 – Spuštění všech pravidel s výjimkou dvou v modulech

Tento příklad spouští všechna pravidla s výjimkou PSAvoidUsingCmdletAliases a PSAvoidUsingInternalURLs pro .ps1 soubory a .psm1 v MyModules adresáři a v jeho podadresářích.

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

PŘÍKLAD 5 – Spuštění Analyzátoru skriptů s vlastními pravidly

Tento příklad spustí Analyzátor skriptů na Test-Script.ps1 se standardními pravidly a pravidly v cestě C:\CommunityAnalyzerRules .

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

PŘÍKLAD 6 – Spusťte pouze pravidla, která jsou závažná jako chyba a mají název zdroje PSDSC.

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

PŘÍKLAD 7 – Potlačení porušení pravidel

Tento příklad ukazuje, jak potlačit hlášení porušení pravidel ve funkci a jak zjistit porušení pravidel, která jsou potlačena.

Příklad používá SuppressMessageAttribute atribut k potlačení PSUseSingularNouns a PSAvoidUsingCmdletAliases pravidla pro Get-Widgets funkci ve Get-Widgets.ps1 skriptu. Tento atribut můžete použít k potlačení pravidla pro modul, skript, třídu, funkci, parametr nebo řádek.

První příkaz spustí Analyzátor skriptů pro soubor skriptu obsahující funkci . Výstup hlásí porušení pravidla. I když dojde k porušení více pravidel, nebude hlášeno ani jedno potlačené pravidlo.

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

Druhý příkaz používá parametr SuppressedOnly k nahlášení porušení pravidel, která jsou potlačeného souboru skriptu.

PŘÍKLAD 8 – Analýza souborů skriptů pomocí definice profilu

V tomto příkladu vytvoříme profil Analyzátoru skriptů a uložíme ho ScriptAnalyzerProfile.txt do souboru v aktuálním adresáři. Spouštíme Invoke-ScriptAnalyzer na souborech modulu Nástroje BitLocker . Hodnota parametru Profile je cesta k profilu Analyzátoru skriptů.

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

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

Pokud do Invoke-ScriptAnalyzer příkazu zahrnete konfliktní parametr, například -Severity Error, rutina použije hodnotu profilu a parametr ignoruje.

PŘÍKLAD 9 – Analýza skriptu uloženého jako řetězec

Tento příklad používá parametr ScriptDefinition k analýze funkce na příkazovém řádku. Řetězec funkce je uzavřený v uvozovkách.

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

Když použijete parametr ScriptDefinition , vlastnost FileName objektu DiagnosticRecord je $null.

Parametry

-Confirm

Před spuštěním rutiny zobrazí výzvu k potvrzení.

Typ:	SwitchParameter
Aliasy:	cf
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-CustomRulePath

Zadejte cestu k souboru, který definuje pravidla, nebo adresář obsahující soubory definující pravidla. Zástupné znaky jsou podporovány. Při zadání CustomRulePath se pro analýzu použijí pouze vlastní pravidla nalezená v zadaných cestách. Pokud Invoke-ScriptAnalyzer nelze najít pravidla v , spustí standardní pravidla bez upozornění.

Chcete-li přidat pravidla definovaná v podadresářích cesty, použijte parametr RecurseCustomRulePath . Pokud chcete zahrnout předdefinované pravidla, přidejte parametr IncludeDefaultRules .

Typ:	String[]
Aliasy:	CustomizedRulePath
Position:	Named
Default value:	None
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	True

-EnableExit

Po dokončení analýzy tento parametr ukončí relace PowerShellu a vrátí ukončovací kód, který se rovná počtu záznamů chyb. To může být užitečné v kanálu kontinuální integrace (CI).

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-ExcludeRule

Vynechá zadaná pravidla z testu analyzátoru skriptů. Zástupné znaky jsou podporovány.

Zadejte čárkami oddělený seznam názvů pravidel, proměnnou obsahující názvy pravidel nebo příkaz, který získá názvy pravidel. Můžete také zadat seznam vyloučených pravidel v souboru profilu analyzátoru skriptů. Standardní pravidla a pravidla můžete vyloučit z vlastní cesty k pravidlu.

Když pravidlo vyloučíte, nespustí se na žádném souboru v cestě. Pokud chcete vyloučit pravidlo pro konkrétní řádek, parametr, funkci, skript nebo třídu, upravte parametr Path nebo potlačit pravidlo. Informace o potlačení pravidla najdete v příkladech.

Pokud je pravidlo zadáno v kolekcích ExcludeRule i IncludeRule , je pravidlo vyloučeno.

Typ:	String[]
Position:	Named
Default value:	All rules are included.
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	True

-Fix

Opravuje některá upozornění, která obsahují opravu v diagnostickémzáznamu.

Pokud jste použili nástroj Fix, Invoke-ScriptAnalyzer před spuštěním analýzy použije opravy. Při použití tohoto parametru se ujistěte, že máte zálohu souborů. Pokouší se zachovat kódování souboru, ale stále existují případy, kdy se kódování může změnit.

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-IncludeDefaultRules

Vyvolání výchozích pravidel spolu s vlastními pravidly

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-IncludeRule

Spustí pouze zadaná pravidla v testu Analyzátoru skriptů. Ve výchozím nastavení PSScriptAnalyzer spouští všechna pravidla.

Zadejte čárkami oddělený seznam názvů pravidel, proměnnou obsahující názvy pravidel nebo příkaz, který získá názvy pravidel. Zástupné znaky jsou podporovány. Názvy pravidel můžete zadat také v souboru profilu analyzátoru skriptů.

Při použití parametru CustomizedRulePath můžete tento parametr použít k zahrnutí standardních pravidel a pravidel do vlastních cest k pravidlům.

Pokud je pravidlo zadáno v kolekcích ExcludeRule i IncludeRule , je pravidlo vyloučeno.

Parametr Severity má přednost před IncludeRule. Pokud je Errornapříklad Závažnost , nemůžete k zahrnutí Warning pravidla použít IncludeRule.

Typ:	String[]
Position:	Named
Default value:	All rules are included.
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	True

-IncludeSuppressed

Do výstupu zahrňte potlačenou diagnostiku.

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	True
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-Path

Určuje cestu ke skriptům nebo modulům, které se mají analyzovat. Zástupné znaky jsou podporovány.

Zadejte cestu ke skriptu (.ps1) nebo souboru modulu (.psm1) nebo k adresáři, který obsahuje skripty nebo moduly. Pokud adresář obsahuje jiné typy souborů, budou ignorovány.

Chcete-li analyzovat soubory, které nejsou v kořenovém adresáři zadané cesty, použijte zástupný znak (C:\Modules\MyModule\*) nebo parametr Recurse .

Typ:	String
Aliasy:	PSPath
Position:	0
Default value:	None
Vyžadováno:	True
Přijmout vstup kanálu:	True
Přijmout zástupné znaky:	True

-Recurse

Spustí analyzátor skriptů pro soubory v adresáři Path a všechny podadresáře rekurzivně.

Recurse se vztahuje pouze na hodnotu parametru Path. Chcete-li hledat CustomRulePath rekurzivně, použijte RecurseCustomRulePath parametr.

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-RecurseCustomRulePath

Přidá pravidla definovaná v podadresářích umístění CustomRulePath . Ve výchozím nastavení Invoke-ScriptAnalyzer používá pouze vlastní pravidla definovaná v zadaném souboru nebo adresáři. Pokud chcete zahrnout předdefinované pravidla, použijte parametr IncludeDefaultRules .

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-ReportSummary

Napište hostiteli souhrn zjištěných porušení.

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-SaveDscDependency

Řešení závislostí prostředků DSC

Při Invoke-ScriptAnalyzer spuštění s tímto parametrem hledá instance Import-DSCResource -ModuleName <somemodule>. Pokud <somemodule> ho nelze najít vyhledáním $env:PSModulePath, Invoke-ScriptAnalyzer vrátí se chyba analýzy. Tato chyba je způsobená tím, že analyzátor PowerShellu nemůže najít symbol pro <somemodule>.

Pokud Invoke-ScriptAnalyzer najde modul v Galerie prostředí PowerShell, stáhne chybějící modul do dočasné cesty. Dočasná cesta se pak přidá do $env:PSModulePath po dobu trvání kontroly. Dočasné umístění najdete v $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir.

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-ScriptDefinition

Spustí analýzu příkazů, funkcí nebo výrazů v řetězci. Tuto funkci můžete použít k analýze příkazů, výrazů a funkcí nezávisle na kontextu skriptu.

Typ:	String
Position:	0
Default value:	None
Vyžadováno:	True
Přijmout vstup kanálu:	True
Přijmout zástupné znaky:	False

-Settings

Cesta k souboru obsahujícímu profil definovaný uživatelem nebo objekt hashtable obsahující nastavení pro ScriptAnalyzer.

Spustí Invoke-ScriptAnalyzer se s parametry a hodnotami zadanými v souboru nebo v zatřiďovací tabulce.

Pokud je cesta nebo obsah souboru nebo hashovací tabulky neplatné, bude ignorován. Parametry a hodnoty v profilu mají přednost před stejným parametrem a hodnotami zadanými na příkazovém řádku.

Soubor profilu analyzátoru skriptů je textový soubor, který obsahuje zatřiďovací tabulku s jedním nebo více z následujících klíčů:

CustomRulePath
Vyloučení pravidel
IncludeDefaultRules
IncludeRules
RecurseCustomRulePath
Pravidla
Závažnost

Klíče a hodnoty v profilu se interpretují, jako by šlo o standardní parametry a hodnoty Invoke-ScriptAnalyzer, podobně jako u splattingu. Další informace najdete v tématu about_Splatting.

Typ:	Object
Aliasy:	Profile
Position:	Named
Default value:	None
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-Severity

Po spuštění Analyzátoru skriptů se všemi pravidly vybere tento parametr porušení pravidel se zadanou závažností.

Platné hodnoty jsou:

Chybová
Upozornění
Informace.

Můžete zadat jednu nebo více hodnot závažnosti.

Parametr filtruje porušení pravidel až po spuštění všech pravidel. Pokud chcete pravidla filtrovat efektivně, vyberte Get-ScriptAnalyzerRule pravidla, která chcete spustit.

Parametr Severity má přednost před IncludeRule. Pokud je Errornapříklad závažnost , nemůžete použít IncludeRule k zahrnutí Warning pravidla.

Typ:	String[]
Position:	Named
Default value:	All rule violations
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-SuppressedOnly

Vrátí porušení pouze pro pravidla, která jsou potlačena.

Vrátí objekt SuppressedRecord (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).

Chcete-li potlačit pravidlo, použijte SuppressMessageAttribute. Nápovědu najdete v příkladech.

Typ:	SwitchParameter
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

-WhatIf

Zobrazuje, co by se stalo při spuštění rutiny. Rutina není spuštěna.

Typ:	SwitchParameter
Aliasy:	wi
Position:	Named
Default value:	False
Vyžadováno:	False
Přijmout vstup kanálu:	False
Přijmout zástupné znaky:	False

Vstupy

None

Vstup do této rutiny nelze vložit do kanálu.

Výstupy

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord

Ve výchozím nastavení Invoke-ScriptAnalyzer vrátí jeden objekt DiagnosticRecord pro každé porušení pravidla.

Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord

Pokud použijete SuppressedOnly parametr, Invoke-ScriptAnalyzer vrátí místo toho SuppressedRecord objekty.

Sdílet prostřednictvím

Invoke-ScriptAnalyzer

Syntaxe

Description

Příklady

PŘÍKLAD 1 – Spuštění všech pravidel Analyzátoru skriptů ve skriptu

PŘÍKLAD 2 – Spuštění všech pravidel Analyzátoru skriptů pro všechny soubory v adresáři Modules

PŘÍKLAD 3 – Spuštění jednoho pravidla pro modul

PŘÍKLAD 4 – Spuštění všech pravidel s výjimkou dvou v modulech

PŘÍKLAD 5 – Spuštění Analyzátoru skriptů s vlastními pravidly

PŘÍKLAD 6 – Spusťte pouze pravidla, která jsou závažná jako chyba a mají název zdroje PSDSC.

PŘÍKLAD 7 – Potlačení porušení pravidel

PŘÍKLAD 8 – Analýza souborů skriptů pomocí definice profilu

PŘÍKLAD 9 – Analýza skriptu uloženého jako řetězec

Parametry

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Vstupy

Výstupy

Další materiály

Sdílet prostřednictvím

Invoke-ScriptAnalyzer

Syntaxe

Description

Příklady

PŘÍKLAD 1 – Spuštění všech pravidel Analyzátoru skriptů ve skriptu

PŘÍKLAD 2 – Spuštění všech pravidel Analyzátoru skriptů pro všechny soubory v adresáři Modules

PŘÍKLAD 3 – Spuštění jednoho pravidla pro modul

PŘÍKLAD 4 – Spuštění všech pravidel s výjimkou dvou v modulech

PŘÍKLAD 5 – Spuštění Analyzátoru skriptů s vlastními pravidly

PŘÍKLAD 6 – Spusťte pouze pravidla, která jsou závažná jako chyba a mají název zdroje PSDSC.

PŘÍKLAD 7 – Potlačení porušení pravidel

PŘÍKLAD 8 – Analýza souborů skriptů pomocí definice profilu

PŘÍKLAD 9 – Analýza skriptu uloženého jako řetězec

Parametry

-Confirm

-CustomRulePath

-EnableExit

-ExcludeRule

-Fix

-IncludeDefaultRules

-IncludeRule

-IncludeSuppressed

-Path

-Recurse

-RecurseCustomRulePath

-ReportSummary

-SaveDscDependency

-ScriptDefinition

-Settings

-Severity

-SuppressedOnly

-WhatIf

Vstupy

Výstupy

Související odkazy

Další materiály