Invoke-ScriptAnalyzer
Ocenia skrypt lub moduł na podstawie wybranych reguł najlepszych rozwiązań
Składnia
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>]
Opis
Invoke-ScriptAnalyzer
ocenia skrypty lub pliki modułów (.ps1
, .psm1
, i .psd1
) na podstawie kolekcji reguł najlepszych rozwiązań i zwraca obiekty reprezentujące naruszenia reguł. Obejmuje ona również specjalne reguły analizowania zasobów DSC.
Invoke-ScriptAnalyzer
jest dostarczany z zestawem wbudowanych reguł. Domyślnie używa wszystkich reguł. Możesz użyć parametrów IncludeRule i ExcludeRule , aby wybrać żądane reguły. Możesz użyć Get-ScriptAnalyzerRule
polecenia cmdlet, aby sprawdzić i wybrać reguły, które chcesz uwzględnić lub wykluczyć z oceny.
Można również użyć niestandardowych reguł pisania w skryptach programu PowerShell lub kompilowania w zestawach przy użyciu języka C#. Reguły niestandardowe można również wybrać przy użyciu parametrów IncludeRule i ExcludeRule .
Regułę można również uwzględnić w analizie, ale pominąć dane wyjściowe tej reguły dla wybranych funkcji lub skryptów. Ta funkcja powinna być używana tylko wtedy, gdy jest to konieczne. Aby uzyskać pominięte reguły, uruchom polecenie Invoke-ScriptAnalyzer
z parametrem SuppressedOnly .
W przypadku użycia w systemach ciągłej integracji funkcja EnableExit zamyka powłokę z kodem zakończenia równym liczbie rekordów błędów.
Przykłady
PRZYKŁAD 1 — uruchamianie wszystkich reguł analizatora skryptów na skrycie
Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1
PRZYKŁAD 2 — uruchamianie wszystkich reguł analizatora skryptów we wszystkich plikach w katalogu Modules
W tym przykładzie są uruchamiane wszystkie reguły analizatora skryptów na wszystkich .ps1
.psm1
plikach i w katalogu opartym na Modules
użytkowniku i jego podkatalogach.
Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse
PRZYKŁAD 3 — Uruchamianie pojedynczej reguły w module
W tym przykładzie jest uruchamiana tylko reguła PSAvoidUsingPositionalParameters w plikach w folderze modułu PSDiagnostics
. Możesz użyć polecenia takiego jak to, aby znaleźć wszystkie wystąpienia określonego naruszenia reguły.
Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters
PRZYKŁAD 4 — Uruchamianie wszystkich reguł z wyjątkiem dwóch w modułach
W tym przykładzie są uruchamiane wszystkie reguły z wyjątkiem parametrów PSAvoidUsingCmdletAliases i PSAvoidUsingInternalURLs w .ps1
katalogu i .psm1
w MyModules
jego podkatalogach.
Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs
PRZYKŁAD 5 — Uruchamianie analizatora skryptów z regułami niestandardowymi
W tym przykładzie jest uruchamiany analizator skryptów przy Test-Script.ps1
użyciu standardowych reguł i reguł w ścieżce C:\CommunityAnalyzerRules
.
Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules -IncludeDefaultRules
PRZYKŁAD 6 — uruchamianie tylko reguł o ważności błędu i nazwa źródła PSDSC
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
PRZYKŁAD 7 — pomijanie naruszeń reguł
W tym przykładzie pokazano, jak pominąć raportowanie naruszeń reguł w funkcji oraz sposób odnajdywania naruszeń reguł, które są pomijane.
W przykładzie użyto atrybutu SuppressMessageAttribute
, aby pominąć reguły PSUseSingularNouns i PSAvoidUsingCmdletAliases dla Get-Widgets
funkcji w Get-Widgets.ps1
skrycie.
Tego atrybutu można użyć do pomijania reguły dla modułu, skryptu, klasy, funkcji, parametru lub wiersza.
Pierwsze polecenie uruchamia narzędzie Script Analyzer w pliku skryptu zawierającym funkcję. Dane wyjściowe zgłasza naruszenie reguły. Mimo naruszenia większej liczby reguł żadna z pominiętych reguł nie jest zgłaszana.
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
Drugie polecenie używa parametru SuppressedOnly do zgłaszania naruszeń reguł, które są pomijane w pliku skryptu.
PRZYKŁAD 8 — Analizowanie plików skryptów przy użyciu definicji profilu
W tym przykładzie utworzymy profil analizatora skryptów i zapiszemy go w ScriptAnalyzerProfile.txt
pliku w bieżącym katalogu. Uruchamiamy na Invoke-ScriptAnalyzer
plikach modułu funkcji BitLocker . Wartość parametru Profilu jest ścieżką do profilu analizatora skryptów.
# In .\ScriptAnalyzerProfile.txt
@{
Severity = @('Error', 'Warning')
IncludeRules = 'PSAvoid*'
ExcludeRules = '*WriteHost'
}
Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Profile .\ScriptAnalyzerProfile.txt
Jeśli w poleceniu zostanie uwzględniny parametr Invoke-ScriptAnalyzer
powodujący konflikt, taki jak -Severity Error
, polecenie cmdlet używa wartości profilu i ignoruje parametr.
PRZYKŁAD 9 — analizowanie skryptu przechowywanego jako ciąg
W tym przykładzie użyto parametru ScriptDefinition do przeanalizowania funkcji w wierszu polecenia. Ciąg funkcji jest ujęta w cudzysłów.
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
W przypadku użycia parametru ScriptDefinition właściwość FileName obiektu DiagnosticRecord to $null
.
Parametry
-Confirm
Monituje o potwierdzenie przed uruchomieniem polecenia cmdlet.
Typ: | SwitchParameter |
Aliasy: | cf |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-CustomRulePath
Wprowadź ścieżkę do pliku definiującego reguły lub katalog zawierający pliki definiujące reguły.
Obsługiwane są symbole wieloznaczne. Po określeniu parametru CustomRulePath do analizy są używane tylko reguły niestandardowe znalezione w określonych ścieżkach. Jeśli Invoke-ScriptAnalyzer
nie można odnaleźć reguł w elemecie , uruchamia standardowe reguły bez powiadomienia.
Aby dodać reguły zdefiniowane w podkatalogach ścieżki, użyj parametru RecurseCustomRulePath . Aby uwzględnić wbudowane reguły, dodaj parametr IncludeDefaultRules .
Typ: | String[] |
Aliasy: | CustomizedRulePath |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | True |
-EnableExit
Po zakończeniu analizy ten parametr kończy sesje programu PowerShell i zwraca kod zakończenia równy liczbie rekordów błędów. Może to być przydatne w potoku ciągłej integracji.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ExcludeRule
Pomija określone reguły z testu analizatora skryptów. Obsługiwane są symbole wieloznaczne.
Wprowadź rozdzielaną przecinkami listę nazw reguł, zmienną zawierającą nazwy reguł lub polecenie, które pobiera nazwy reguł. Listę wykluczonych reguł można również określić w pliku profilu analizatora skryptów. Standardowe reguły i reguły można wykluczyć w niestandardowej ścieżce reguły.
Po wykluczeniu reguły reguła nie jest uruchamiana na żadnym z plików w ścieżce. Aby wykluczyć regułę w określonym wierszu, parametrze, funkcji, skryscie lub klasie, dostosuj parametr Path lub pomiń regułę. Aby uzyskać informacje na temat pomijania reguły, zobacz przykłady.
Jeśli reguła zostanie określona zarówno w kolekcjach ExcludeRule , jak i IncludeRule , reguła zostanie wykluczona.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | All rules are included. |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | True |
-Fix
Naprawia niektóre ostrzeżenia, które zawierają poprawkę w ich diagnosticRecord.
W przypadku użycia poprawkiInvoke-ScriptAnalyzer
stosuje poprawki przed uruchomieniem analizy. Upewnij się, że masz kopię zapasową plików podczas korzystania z tego parametru. Próbuje zachować kodowanie pliku, ale nadal istnieją pewne przypadki, w których kodowanie może ulec zmianie.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-IncludeDefaultRules
Wywołaj reguły domyślne wraz z regułami niestandardowymi.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-IncludeRule
Uruchamia tylko określone reguły w teście analizatora skryptów. Domyślnie program PSScriptAnalyzer uruchamia wszystkie reguły.
Wprowadź rozdzielaną przecinkami listę nazw reguł, zmienną zawierającą nazwy reguł lub polecenie, które pobiera nazwy reguł. Obsługiwane są symbole wieloznaczne. Nazwy reguł można również określić w pliku profilu analizatora skryptów.
W przypadku używania parametru CustomizedRulePath można użyć tego parametru do uwzględnienia standardowych reguł i reguł w niestandardowych ścieżkach reguł.
Jeśli reguła zostanie określona zarówno w kolekcjach ExcludeRule , jak i IncludeRule , reguła zostanie wykluczona.
Parametr Ważność ma pierwszeństwo przed parametrem IncludeRule. Jeśli na przykład ważność to Error
, nie można użyć metody IncludeRule do uwzględnienia Warning
reguły.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | All rules are included. |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | True |
-IncludeSuppressed
Uwzględnij pominiętą diagnostykę w danych wyjściowych.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Path
Określa ścieżkę do skryptów lub modułu do przeanalizowania. Obsługiwane są symbole wieloznaczne.
Wprowadź ścieżkę do skryptu () lub pliku modułu (.ps1
.psm1
) lub katalogu zawierającego skrypty lub moduły. Jeśli katalog zawiera inne typy plików, są one ignorowane.
Aby analizować pliki, które nie znajdują się w katalogu głównym określonej ścieżki, użyj symbolu wieloznakowego (C:\Modules\MyModule\*
) lub parametru Recurse .
Typ: | String |
Aliasy: | PSPath |
Position: | 0 |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | True |
-Recurse
Uruchamia analizator skryptów w plikach w katalogu Path i wszystkie podkatalogi cyklicznie.
Recurse ma zastosowanie tylko do wartości parametru Ścieżka. Aby wyszukać parametr CustomRulePath cyklicznie, użyj parametru RecurseCustomRulePath .
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-RecurseCustomRulePath
Dodaje reguły zdefiniowane w podkatalogach lokalizacji CustomRulePath . Domyślnie Invoke-ScriptAnalyzer
używa tylko niestandardowych reguł zdefiniowanych w określonym pliku lub katalogu. Aby uwzględnić wbudowane reguły, użyj parametru IncludeDefaultRules .
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ReportSummary
Napisz podsumowanie naruszeń znalezionych na hoście.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-SaveDscDependency
Rozwiązywanie problemów z zależnościami zasobów DSC.
Po Invoke-ScriptAnalyzer
uruchomieniu za pomocą tego parametru wyszukuje wystąpienia elementu Import-DSCResource -ModuleName <somemodule>
. Jeśli <somemodule>
nie można odnaleźć elementu, wyszukując $env:PSModulePath
parametr , Invoke-ScriptAnalyzer
zwraca błąd analizy. Ten błąd jest spowodowany tym, że analizator programu PowerShell nie może odnaleźć symbolu dla <somemodule>
elementu .
Jeśli Invoke-ScriptAnalyzer
znajdzie moduł w Galeria programu PowerShell, pobierze brakujący moduł do ścieżki tymczasowej. Ścieżka tymczasowa jest następnie dodawana do $env:PSModulePath
elementu na czas trwania skanowania.
Lokalizację tymczasową można znaleźć w pliku $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir
.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-ScriptDefinition
Uruchamia analizę poleceń, funkcji lub wyrażeń w ciągu. Ta funkcja umożliwia analizowanie instrukcji, wyrażeń i funkcji niezależnie od kontekstu skryptu.
Typ: | String |
Position: | 0 |
Domyślna wartość: | None |
Wymagane: | True |
Akceptowanie danych wejściowych potoku: | True |
Akceptowanie symboli wieloznacznych: | False |
-Settings
Ścieżka do pliku zawierającego profil zdefiniowany przez użytkownika lub obiekt z tabelą skrótów zawierającą ustawienia elementu ScriptAnalyzer.
Uruchamia polecenie Invoke-ScriptAnalyzer
z parametrami i wartościami określonymi w pliku lub tabeli skrótów.
Jeśli ścieżka lub zawartość pliku lub tabeli skrótów jest nieprawidłowa, jest ignorowana. Parametry i wartości w profilu mają pierwszeństwo przed tym samym parametrem i wartościami określonymi w wierszu polecenia.
Plik profilu analizatora skryptów jest plikiem tekstowym zawierającym tabelę skrótów z co najmniej jednym z następujących kluczy:
- CustomRulePath
- Reguły wykluczania
- IncludeDefaultRules
- Reguły dołączania
- RecurseCustomRulePath
- Reguły
- Ważność
Klucze i wartości w profilu są interpretowane tak, jakby były standardowymi parametrami i wartościami Invoke-ScriptAnalyzer
, podobnie jak w przypadku platania. Aby uzyskać więcej informacji, zobacz about_Splatting.
Typ: | Object |
Aliasy: | Profile |
Position: | Named |
Domyślna wartość: | None |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-Severity
Po uruchomieniu analizatora skryptów ze wszystkimi regułami ten parametr wybiera naruszenia reguły z określoną ważnością.
Prawidłowe wartości:
- Błąd
- Ostrzeżenie
- Informacji.
Można określić jedną lub większą liczbę wartości ważności.
Parametr filtruje naruszenia reguł tylko po uruchomieniu wszystkich reguł. Aby efektywnie filtrować reguły, użyj polecenia Get-ScriptAnalyzerRule
, aby wybrać reguły, które chcesz uruchomić.
Parametr Ważność ma pierwszeństwo przed parametrem IncludeRule. Jeśli na przykład ważność to Error
, nie można użyć reguły IncludeRule do uwzględnienia Warning
reguły.
Typ: | String[] |
Position: | Named |
Domyślna wartość: | All rule violations |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-SuppressedOnly
Zwraca naruszenia tylko dla reguł, które są pomijane.
Zwraca obiekt SuppressedRecord (Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord).
Aby pominąć regułę, użyj atrybutu SuppressMessageAttribute. Aby uzyskać pomoc, zobacz przykłady.
Typ: | SwitchParameter |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
-WhatIf
Pokazuje, co się stanie po uruchomieniu polecenia cmdlet. Polecenie cmdlet nie zostało uruchomione.
Typ: | SwitchParameter |
Aliasy: | wi |
Position: | Named |
Domyślna wartość: | False |
Wymagane: | False |
Akceptowanie danych wejściowych potoku: | False |
Akceptowanie symboli wieloznacznych: | False |
Dane wejściowe
None
Nie można przekazać potoku danych wejściowych do tego polecenia cmdlet.
Dane wyjściowe
Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord
Domyślnie Invoke-ScriptAnalyzer
zwraca jeden obiekt DiagnosticRecord dla każdego naruszenia reguły.
Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord
Jeśli używasz parametru SuppressedOnly , Invoke-ScriptAnalyzer
zamiast tego zwraca obiekty SuppressedRecord .