Menggunakan PSScriptAnalyzer

Artikel ini menjelaskan berbagai fitur PSScriptAnalyzer dan cara menggunakannya.

Kesalahan Parser

Dimulai pada versi 1.18.0, PSScriptAnalyzer memancarkan kesalahan parser sebagai catatan diagnostik dalam aliran output.

Invoke-ScriptAnalyzer -ScriptDefinition '"b" = "b"; function eliminate-file () { }'

RuleName            Severity   ScriptName Line Message
--------            --------   ---------- ---- -------
InvalidLeftHandSide ParseError            1    The assignment expression isn't
                                               valid. The input to an
                                               assignment operator must be an
                                               object that's able to accept
                                               assignments, such as a variable
                                               or a property.
PSUseApprovedVerbs  Warning               1    The cmdlet 'eliminate-file' uses an
                                               unapproved verb.

RuleName diatur ke ErrorId dari kesalahan pengurai.

Untuk menekan ParseErrors, jangan sertakan sebagai nilai dalam parameter Severity .

$invokeScriptAnalyzerSplat = @{
    ScriptDefinition = '"b" = "b"; function eliminate-file () { }'
    Severity = 'Warning'
}
Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat

RuleName           Severity ScriptName Line Message
--------           -------- ---------- ---- -------
PSUseApprovedVerbs Warning             1    The cmdlet 'eliminate-file' uses an
                                            unapproved verb.

Menekan Aturan

Anda dapat menekan aturan dengan menghias skrip, fungsi, atau parameter dengan . SuppressMessageAttribute NET. Konstruktor untuk SuppressMessageAttribute mengambil dua parameter: kategori dan ID cek. Atur parameter categoryID ke nama aturan yang ingin Anda tekan dan atur parameter checkID ke string null atau kosong. Anda dapat secara opsional menambahkan parameter bernama ketiga dengan pembenaran untuk menekan pesan:

function SuppressMe()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideCommentHelp', '',
        Justification='Just an example')]
    param()

    Write-Verbose -Message "I'm making a difference!"

}

Dalam cakupan skrip, fungsi, atau parameter yang Anda dekorasi, semua pelanggaran aturan ditekan.

Untuk menekan pesan pada parameter tertentu, atur parameter CheckIdSuppressMessageAttribute ke nama parameter:

function SuppressTwoVariables()
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideDefaultParameterValue', 'b')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideDefaultParameterValue', 'a')]
    param([string]$a, [int]$b)
    {
    }
}

Gunakan properti CakupanSuppressMessageAttribute untuk membatasi penekanan aturan ke fungsi atau kelas dalam cakupan atribut.

Gunakan nilai Function untuk menekan pelanggaran pada semua fungsi dalam cakupan atribut. Gunakan nilai Class untuk menekan pelanggaran pada semua kelas dalam cakupan atribut:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSProvideCommentHelp', '', Scope='Function')]
param()

function InternalFunction
{
    param()

    Write-Verbose -Message "I am invincible!"
}

Anda dapat membatasi penekanan lebih lanjut berdasarkan fungsi, parameter, kelas, variabel, atau nama objek dengan mengatur properti TargetSuppressMessageAttribute ke ekspresi reguler atau pola karakter pengganti.

Misalnya, untuk menekan pelanggaran aturan PSAvoidUsingWriteHost di start-bar dan start-baz tetapi tidak di start-foo dan start-bam:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='start-ba[rz]')]
param()
function start-foo {
    write-host "start-foo"
}

function start-bar {
    write-host "start-bar"
}

function start-baz {
    write-host "start-baz"
}

function start-bam {
    write-host "start-bam"
}

Untuk menekan pelanggaran di semua fungsi:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='*')]
Param()

Untuk menekan pelanggaran di start-bar, start-baz dan start-bam tetapi tidak di start-foo:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '',
    Scope='Function', Target='start-b*')]
Param()

Nota

Kesalahan pengurai tidak dapat ditekan dengan SuppressMessageAttribute.

Dukungan Pengaturan di ScriptAnalyzer

Anda dapat membuat pengaturan yang menjelaskan aturan ScriptAnalyzer untuk disertakan atau dikecualikan berdasarkan Tingkat Keparahan. Gunakan parameter Pengaturan untuk Invoke-ScriptAnalyzer menentukan konfigurasi. Parameter Pengaturan memungkinkan Anda membuat konfigurasi kustom untuk lingkungan tertentu. ScriptAnalyzer mendukung mode berikut untuk menentukan file pengaturan:

Preset bawaan

ScriptAnalyzer mengirimkan serangkaian preset bawaan yang dapat digunakan untuk menganalisis skrip. Misalnya, jika Anda ingin menjalankan aturan Galeri PowerShell pada modul Anda, gunakan perintah berikut:

Invoke-ScriptAnalyzer -Path /path/to/module/ -Settings PSGallery -Recurse

Selain itu, Anda dapat menggunakan preset bawaan lainnya, termasuk DSC dan CodeFormatting. Preset ini dapat diselesaikan tab untuk parameter Pengaturan .

Eksplisit

Contoh berikut mengecualikan dua aturan dari kumpulan aturan default dan aturan apa pun dengan tingkat keparahan selain Kesalahan dan Peringatan.

# PSScriptAnalyzerSettings.psd1
@{
    Severity=@('Error','Warning')
    ExcludeRules=@('PSAvoidUsingCmdletAliases', 'PSAvoidUsingWriteHost')
}

Anda kemudian dapat memanggil file pengaturan tersebut dengan Invoke-ScriptAnalyzer:

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1

Contoh berikutnya memilih beberapa aturan untuk dieksekusi alih-alih semua aturan default.

# PSScriptAnalyzerSettings.psd1
@{
    IncludeRules=@('PSAvoidUsingPlainTextForPassword',
                'PSAvoidUsingConvertToSecureStringWithPlainText')
}

Anda kemudian dapat memanggil file pengaturan tersebut:

Invoke-ScriptAnalyzer -Path MyScript.ps1 -Settings PSScriptAnalyzerSettings.psd1

Implisit

Jika Anda menempatkan file pengaturan bernama di PSScriptAnalyzerSettings.psd1 root project Anda, PSScriptAnalyzer menemukannya saat Anda meneruskan root project sebagai parameter Path .

Invoke-ScriptAnalyzer -Path "C:\path\to\project" -Recurse

Memberikan pengaturan secara eksplisit lebih diutamakan daripada mode implisit ini. Anda dapat menemukan contoh file pengaturan di Settings folder modul PSScriptAnalyzer .

Periksa kompatibilitas versi PowerShell

PSScriptAnalyzer dapat memeriksa skrip PowerShell untuk ketidakcocokan dengan versi dan lingkungan PowerShell lainnya. PSScriptAnalyzer menyertakan empat aturan yang memeriksa masalah kompatibilitas:

• PSUseCompatibleCmdlets memeriksa apakah cmdlet yang digunakan dalam skrip tersedia di lingkungan PowerShell lainnya
• PSUseCompatibleCommands memeriksa apakah perintah yang digunakan dalam skrip tersedia di lingkungan PowerShell lainnya
• PSUseCompatibleSyntax memeriksa apakah sintaks yang digunakan dalam skrip kompatibel di versi PowerShell lainnya
• PSUseCompatibleTypes memeriksa apakah jenis .NET dan metode atau properti statis tersedia di lingkungan PowerShell lainnya

Untuk informasi selengkapnya tentang cara menggunakan aturan ini, lihat Menggunakan PSScriptAnalyzer untuk memeriksa kompatibilitas versi PowerShell di blog Tim PowerShell.

Aturan khusus

Dimungkinkan untuk menyediakan satu atau beberapa jalur ke aturan kustom dalam file pengaturan. Penting bahwa jalur ini mengarah ke folder modul, yang secara implisit menggunakan manifes modul, atau ke file skrip modul (.psm1). Modul harus mengekspor fungsi aturan kustom agar Export-ModuleMember tersedia untuk PSScriptAnalyzer.

Dalam contoh ini, properti CustomRulePath menunjuk ke dua modul yang berbeda. Kedua modul mengekspor fungsi aturan dengan kata kerja Measure sehingga Measure-* digunakan untuk properti IncludeRules.

@{
    CustomRulePath      = @(
        '.\output\RequiredModules\DscResource.AnalyzerRules'
        '.\tests\QA\AnalyzerRules\SqlServerDsc.AnalyzerRules.psm1'
    )

    IncludeRules        = @(
        'Measure-*'
    )
}

Anda juga dapat menambahkan aturan default dengan mencantumkan aturan di properti IncludeRules . Saat menyertakan aturan default, penting bagi Anda untuk mengatur properti IncludeDefaultRules ke $true; jika tidak, aturan default akan digunakan.

@{
    CustomRulePath      = @(
        '.\output\RequiredModules\DscResource.AnalyzerRules'
        '.\tests\QA\AnalyzerRules\SqlServerDsc.AnalyzerRules.psm1'
    )

    IncludeDefaultRules = $true

    IncludeRules        = @(
        # Default rules
        'PSAvoidDefaultValueForMandatoryParameter'
        'PSAvoidDefaultValueSwitchParameter'

        # Custom rules
        'Measure-*'
    )
}

Menggunakan aturan kustom di Visual Studio Code (VS Code)

Anda juga dapat menggunakan aturan kustom yang disediakan dalam file pengaturan di VS Code. Tambahkan file pengaturan ruang kerja VS Code (.vscode/settings.json) dengan konten berikut.

{
    "powershell.scriptAnalysis.settingsPath": ".vscode/analyzersettings.psd1",
    "powershell.scriptAnalysis.enable": true,
}

ScriptAnalyzer sebagai pustaka .NET

Anda dapat langsung menggunakan mesin dan fungsionalitas ScriptAnalyzer sebagai pustaka.

Berikut adalah antarmuka publik:

using Microsoft.Windows.PowerShell.ScriptAnalyzer;

public void Initialize(System.Management.Automation.Runspaces.Runspace runspace,
Microsoft.Windows.PowerShell.ScriptAnalyzer.IOutputWriter outputWriter,
[string[] customizedRulePath = null],
[string[] includeRuleNames = null],
[string[] excludeRuleNames = null],
[string[] severity = null],
[bool suppressedOnly = false],
[string profile = null])

public System.Collections.Generic.IEnumerable<DiagnosticRecord> AnalyzePath(string path,
    [bool searchRecursively = false])

public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames,
    string[] ruleNames)

Koreksi Pelanggaran

Anda dapat menggunakan tombol Perbaiki untuk secara otomatis mengganti konten penyebab pelanggaran dengan alternatif yang disarankan. Selain itu, karena Invoke-ScriptAnalyzer mengimplementasikan SupportsShouldProcess, Anda dapat menggunakan WhatIf atau Confirm untuk mengetahui koreksi mana yang akan diterapkan. Anda harus menggunakan kontrol sumber saat menerapkan koreksi karena beberapa perubahan, seperti yang berlaku untuk AvoidUsingPlainTextForPassword, mungkin memerlukan modifikasi skrip lain yang tidak dapat dilakukan secara otomatis. Pengodean awal tidak selalu dapat dipertahankan saat Anda menerapkan saran secara otomatis. Anda harus memeriksa pengodean file jika skrip Anda bergantung pada pengkodean tertentu.

Properti SuggestedCorrections dari rekaman kesalahan memungkinkan skenario perbaikan cepat di editor seperti VS Code. Kami menyediakan Koreksi yang Disarankan yang valid untuk aturan berikut:

• Hindari Alias
• Menghindari MenggunakanPlainTextForPassword
• Backtick yang menyesatkan
• MissingModuleManifestField
• UseToExportFieldsInManifest