Udostępnij za pośrednictwem


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:PSModulePathparametr , 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 .