Partager via

Utilisation de PSScriptAnalyzer

Cet article décrit les différentes fonctionnalités de PSScriptAnalyzer et leur utilisation.

Erreurs d’analyseur

À partir de la version 1.18.0, PSScriptAnalyzer émet des erreurs d’analyseur en tant qu’enregistrements de diagnostic dans le flux de sortie.

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.

Le RuleName est défini sur l’ErrorId de l’erreur d’analyseur.

Pour supprimer ParseErrors, ne l’incluez pas en tant que valeur dans le paramètre Severity (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.

Suppression des règles

Vous pouvez supprimer une règle en décorant un script, une fonction ou un paramètre avec . SuppressMessageAttribute de NET. Le constructeur de SuppressMessageAttribute prend deux paramètres : une catégorie et un ID de vérification. Définissez le paramètre categoryID sur le nom de la règle que vous souhaitez supprimer et définissez le paramètre checkID sur une chaîne nulle ou vide. Vous pouvez éventuellement ajouter un troisième paramètre nommé avec une justification pour supprimer le message :

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

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

}

Dans le cadre du script, de la fonction ou du paramètre que vous avez décoré, toutes les violations de règle sont supprimées.

Pour supprimer un message sur un paramètre spécifique, définissez le paramètre CheckId de SuppressMessageAttribute sur le nom du paramètre :

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

Utilisez la propriété Scope de SuppressMessageAttribute pour limiter la suppression des règles aux fonctions ou aux classes dans l’étendue de l’attribut.

Utilisez la valeur Fonction pour supprimer les violations sur toutes les fonctions dans la portée de l’attribut. Utilisez la valeur Class pour supprimer les violations sur toutes les classes dans la portée de l’attribut :

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

function InternalFunction
{
    param()

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

Vous pouvez encore restreindre la suppression en fonction d’une fonction, d’un paramètre, d’une classe, d’une variable ou d’un objet en définissant la propriété Target de SuppressMessageAttribute sur une expression régulière ou un motif de jokers.

Par exemple, pour supprimer la violation de la règle PSAvoidUsingWriteHost dans start-bar et mais start-baz pas dans start-foo et 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"
}

Pour supprimer les violations dans toutes les fonctions :

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

Pour réprimer les violations dans start-bar, start-baz mais start-bam pas dans start-foo:

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

Note

Les erreurs d’analyseur ne peuvent pas être supprimées avec SuppressMessageAttribute.

Prise en charge des paramètres dans ScriptAnalyzer

Vous pouvez créer des paramètres qui décrivent les règles ScriptAnalyzer à inclure ou à exclure en fonction de la gravité. Utilisez le paramètre Settings de Invoke-ScriptAnalyzer pour spécifier la configuration. Le paramètre Paramètres permet de créer une configuration personnalisée pour un environnement spécifique. ScriptAnalyzer prend en charge les modes suivants pour spécifier le fichier de paramètres :

Préréglages intégrés

ScriptAnalyzer fournit un ensemble de préréglages intégrés qui peuvent être utilisés pour analyser les scripts. Par exemple, si vous souhaitez exécuter des règles PowerShell Gallery sur votre module, utilisez la commande suivante :

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

De plus, vous pouvez utiliser d’autres préréglages intégrés, notamment DSC et CodeFormatting. Ces préréglages peuvent être complétés par tabulation pour le paramètre Paramètres .

Explicit

L’exemple suivant exclut deux règles de l’ensemble de règles par défaut et toute règle dont la gravité est autre que Erreur et Avertissement.

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

Vous pouvez ensuite invoquer ce fichier de paramètres avec Invoke-ScriptAnalyzer:

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

L’exemple suivant sélectionne quelques règles à exécuter au lieu de toutes les règles par défaut.

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

Vous pouvez ensuite appeler ce fichier de paramètres :

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

Implicite

Si vous placez un fichier de paramètres nommé PSScriptAnalyzerSettings.psd1 à la racine de votre projet, PSScriptAnalyzer le détecte lorsque vous transmettez la racine du projet en tant que paramètre Path .

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

Fournir des réglages explicitement prime davantage que ce mode implicite. Vous pouvez trouver des fichiers d’exemples de paramètres dans le Settings dossier du module PSScriptAnalyzer .

Vérifier la compatibilité des versions de PowerShell

PSScriptAnalyzer peut vérifier les scripts PowerShell pour détecter les incompatibilités avec d’autres versions et environnements PowerShell. PSScriptAnalyzer comprend quatre règles qui vérifient les problèmes de compatibilité :

  • PSUseCompatibleCmdlets vérifie si les applets de commande utilisées dans un script sont disponibles dans d’autres environnements PowerShell
  • PSUseCompatibleCommands vérifie si les commandes utilisées dans un script sont disponibles dans d’autres environnements PowerShell
  • PSUseCompatibleSyntax vérifie si une syntaxe utilisée dans un script est compatible avec d’autres versions de PowerShell
  • PSUseCompatibleTypes vérifie si les types .NET et les méthodes ou propriétés statiques sont disponibles dans d’autres environnements PowerShell

Pour plus d’informations sur l’utilisation de ces règles, consultez Utilisation de PSScriptAnalyzer pour vérifier la compatibilité des versions de PowerShell sur le blog de l’équipe PowerShell.

Règles personnalisées

Il est possible de fournir un ou plusieurs chemins d’accès aux règles personnalisées dans le fichier de paramètres. Il est important que ces chemins pointent soit vers le dossier d’un module, qui utilise implicitement le manifeste du module, soit vers le fichier de script du module (.psm1). Le module doit exporter les fonctions de règle personnalisées pour Export-ModuleMember qu’elles soient disponibles pour PSScriptAnalyzer.

Dans cet exemple, la propriété CustomRulePath pointe vers deux modules différents. Les deux modules exportent les fonctions de règle avec le verbe Measure so Measure-* est utilisé pour la propriété IncludeRules.

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

    IncludeRules        = @(
        'Measure-*'
    )
}

Vous pouvez également ajouter des règles par défaut en répertoriant les règles dans la propriété IncludeRules . Lorsque vous incluez des règles par défaut, il est important de définir la propriété IncludeDefaultRules sur $true; sinon, les règles par défaut sont utilisées.

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

    IncludeDefaultRules = $true

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

        # Custom rules
        'Measure-*'
    )
}

Utilisation de règles personnalisées dans Visual Studio Code (VS Code)

Vous pouvez aussi utiliser les règles personnalisées fournies dans le fichier de paramètres dans VS Code. Ajoutez un fichier de paramètres d’espace de travail VS Code (.vscode/settings.json) avec le contenu suivant.

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

ScriptAnalyzer en tant que bibliothèque .NET

Vous pouvez utiliser directement le moteur et les fonctionnalités de ScriptAnalyzer en tant que bibliothèque.

Voici les interfaces publiques :

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)

Correction des infractions

Vous pouvez utiliser l’interrupteur Fix pour remplacer automatiquement le contenu responsable de la violation par une alternative suggérée. De plus, étant donné qu’il Invoke-ScriptAnalyzerimplémente SupportsShouldProcess, vous pouvez utiliser WhatIf ou Confirm pour déterminer quelles corrections seraient appliquées. Vous devriez utiliser le contrôle de version lors de l’application des corrections, car certains changements, comme celui d’AvoidingTextWordForPassword, peuvent nécessiter d’autres modifications de script qui ne peuvent pas être effectuées automatiquement. L’encodage initial ne peut pas toujours être préservé quand on applique automatiquement des suggestions. Vous devriez vérifier l’encodage des fichiers si vos scripts dépendent d’un codage particulier.

La propriété SuggestedCorrections de l’enregistrement d’erreur permet des scénarios de correction rapide dans des éditeurs comme VS Code. Nous fournissons une correction suggérée valide pour les règles suivantes :

  • ÉviterAlias
  • EviterUsingPlainTextForPassword
  • TrompeurApostrophe inversée
  • MissingModuleManifestField
  • UseToExportFieldsInManifest
  • Last updated on