PSScriptAnalyzer kullanma

Bu makalede PSScriptAnalyzer'ın çeşitli özellikleri ve bunların nasıl kullanılacağı açıklanmaktadır.

Ayrıştırıcı Hataları

Sürüm 1.18.0'dan başlayarak, PSScriptAnalyzer ayrıştırıcı hatalarını çıkış akışında tanılama kayıtları olarak yayar.

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, ayrıştırıcı hatasının ErrorId değerine ayarlanır.

ParseErrors'ı gizlemek için bunu Severity parametresine değer olarak eklemeyin.

$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.

Bastırma Kuralları

Bir komut dosyasını, işlevi veya parametreyi ile süsleyerek bir kuralı gizleyebilirsiniz. NET'in SuppressMessageAttribute'unu kullanın. SuppressMessageAttribute oluşturucusu iki parametre alır: kategori ve denetim kimliği. categoryID parametresini gizlemek istediğiniz kuralın adına ayarlayın ve checkID parametresini null veya boş bir dize olarak ayarlayın. İsteğe bağlı olarak, iletiyi gizlemek için bir gerekçe içeren üçüncü bir adlandırılmış parametre ekleyebilirsiniz:

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

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

}

Süslediğiniz komut dosyası, işlev veya parametre kapsamında tüm kural ihlalleri gizlenir.

Belirli bir parametredeki iletiyi gizlemek için CheckId parametresini SuppressMessageAttribute parametresinin adına ayarlayın:

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

Kural gizlemeyi özniteliğin kapsamındaki işlevler veya sınıflarla sınırlamak için SuppressMessageAttribute'unScope özelliğini kullanın.

Özniteliğin kapsamındaki tüm işlevlerdeki ihlalleri gizlemek için İşlev değerini kullanın. Özniteliğin kapsamındaki tüm sınıflardaki ihlalleri gizlemek için Class değerini kullanın:

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

function InternalFunction
{
    param()

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

SuppressMessageAttribute'unTarget özelliğini düzenli ifade veya joker desenine ayarlayarak bir fonksiyon, parametre, sınıf, değişken veya nesnenin adına göre bastırmayı daha da kısıtlayabilirsiniz.

Örneğin, içinde PSAvoidUsingWriteHost kural ihlalini start-barstart-baz ve içinde ve değil start-foostart-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"
}

Tüm işlevlerdeki ihlalleri gizlemek için:

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

'deki start-barihlalleri bastırmak için ve start-bazstart-bam ancak içinde start-foodeğil:

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

ScriptAnalyzer'da Ayarlar Desteği

Önem Derecesine göre dahil edilecek veya dışlanacak ScriptAnalyzer kurallarını açıklayan ayarlar oluşturabilirsiniz. Yapılandırmayı belirtmek için AyarlarInvoke-ScriptAnalyzer parametresini kullanın. Settings parametresi, belirli bir ortam için özel bir yapılandırma oluşturmanıza olanak tanır. ScriptAnalyzer, ayarlar dosyasını belirtmek için aşağıdaki modları destekler:

Yerleşik Ön Ayarlar

ScriptAnalyzer, betikleri analiz etmek için kullanılabilecek bir dizi yerleşik ön ayar sunar. Örneğin, modülünüzde PowerShell Galerisi kurallarını çalıştırmak istiyorsanız aşağıdaki komutu kullanın:

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

Ayrıca, DSC ve CodeFormatting dahil olmak üzere diğer yerleşik hazır ayarları kullanabilirsiniz. Bu ön ayarlar, Ayarlar parametresi için sekme ile tamamlanabilir.

Açık

Aşağıdaki örnek, varsayılan kural kümesinden iki kuralı ve Hata ve Uyarı dışında önem derecesine sahip tüm kuralları dışlar.

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

Daha sonra bu ayarlar dosyasını şununla Invoke-ScriptAnalyzerçağırabilirsiniz:

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

Sonraki örnek, tüm varsayılan kurallar yerine yürütülecek birkaç kural seçer.

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

Daha sonra bu ayarlar dosyasını çağırabilirsiniz:

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

Dolaylı

Proje kökünüze adlı PSScriptAnalyzerSettings.psd1 bir ayarlar dosyası yerleştirirseniz, proje kökünü Path parametresi olarak geçirdiğinizde PSScriptAnalyzer bunu bulur.

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

Ayarların açıkça sağlanması, bu örtük moddan daha önceliklidir. Örnek ayarlar dosyalarını PSScriptAnalyzerSettings modülünün klasöründe bulabilirsiniz.

PowerShell sürüm uyumluluğunu kontrol edin

PSScriptAnalyzer , PowerShell betiklerini diğer PowerShell sürümleri ve ortamlarıyla uyumsuzluklara karşı denetleyebilir. PSScriptAnalyzer uyumluluk sorunlarını denetleyen dört kural içerir:

• PSUseCompatibleCmdlets , bir betikte kullanılan cmdlet'lerin diğer PowerShell ortamlarında kullanılabilir olup olmadığını denetler
• PSUseCompatibleCommands , bir betikte kullanılan komutların diğer PowerShell ortamlarında kullanılabilir olup olmadığını denetler
• PSUseCompatibleSyntax , bir scriptte kullanılan bir sözdiziminin PowerShell'in diğer sürümleriyle uyumlu olup olmadığını kontrol eder
• PSUseCompatibleType , .NET türlerinin ve statik yöntemlerin veya özelliklerin diğer PowerShell ortamlarında kullanılabilir olup olmadığını denetler

Bu kuralların nasıl kullanılacağı hakkında daha fazla bilgi için PowerShell Ekibi blogunda PowerShell sürüm uyumluluğunu denetlemek için PSScriptAnalyzer'ı kullanma bölümüne bakın.

Özel kurallar

Ayarlar dosyasında özel kurallara bir veya daha fazla yol sağlamak mümkündür. Bu yolların, modül bildirimini örtük olarak kullanan bir modülün klasörüne veya modülün betik dosyasına (.psm1) işaret etmesi önemlidir. Modülün, Export-ModuleMember tarafından kullanılabilmesi için özel kural işlevlerini kullanarak dışarı aktarması gerekir.

Bu örnekte, CustomRulePath özelliği iki farklı modüle işaret eder. Her iki modül de kural işlevlerini Measure fiiliyle dışarı aktarır, bu nedenle Measure-*IncludeRules özelliği için kullanılır.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

IncludeRules özelliğinde kuralları listeleyerek de varsayılan kurallar ekleyebilirsiniz. Varsayılan kuralları eklerken, IncludeDefaultRules özelliğini olarak $trueayarlamanız önemlidir; aksi takdirde varsayılan kurallar kullanılır.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Visual Studio Code'da özel kuralların kullanımı (VS Code)

Ayrıca VS Code içindeki ayarlar dosyasında bulunan özel kuralları da kullanabilirsiniz. Aşağıdaki içeriklerle bir VS Code çalışma alanı ayarları dosyası (.vscode/settings.json) ekleyin.

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

.NET kitaplığı olarak ScriptAnalyzer

ScriptAnalyzer'ın altyapısını ve işlevselliğini doğrudan kitaplık olarak kullanabilirsiniz.

İşte genel arayüzler:

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)

İhlal Düzeltme

Düzeltme anahtarını kullanarak ihlal yaratan içeriği önerilen bir alternatifle otomatik olarak değiştirebilirsiniz. Ayrıca, Invoke-ScriptAnalyzer uyguladığından, hangi düzeltmelerin uygulanacağını bulmak için WhatIf veya Confirm kullanabilirsiniz. Düzeltmeler uygularken kaynak kontrolünü kullanmalısınız çünkü AvoidUsingPlainTextForPassword gibi bazı değişiklikler, otomatik olarak yapılamayan başka script değişiklikleri gerektirebilir. İlk kodlama otomatik olarak öneriler uyguladığınızda her zaman korunamaz. Dosya kodlamasını kontrol etmelisiniz, scriptleriniz belirli bir kodlamaya bağlıdır.

Hata kaydının SuggestedCorrections özelliği, VS Code gibi editörlerde hızlı düzeltme senaryolarını mümkün kılar. Aşağıdaki kurallar için geçerli SuggestedCorrection sağlıyoruz:

• Takma Addan Kaçının
• Parola İçin Düz Metin Kullanmaktan Kaçının
• YanıltıcıBacktick
• MissingModuleManifestField
• UseToExportFieldsInManifest