UseCompatibleCommands

livello di gravità : avviso

Descrizione

Questa regola rileva i comandi non disponibili sulla piattaforma PowerShell di cui sei destinata.

Un nome nella piattaforma PowerShell è identificato nel seguente formato:

<os-name>_<os-arch>_<os-version>_<ps-version>_<ps-arch>_<dotnet-version>_<dotnet-edition>

Dove:

• <os-name>: il nome del sistema operativo in cui è in esecuzione PowerShell. Su Windows, il numero SKU è incluso. Su Linux, il valore è il nome della distribuzione.
• <os-arch>: L'architettura della macchina su cui il sistema operativo gira (di solito x64).
• <os-version>: La versione auto-riportata del sistema operativo (la versione di distribuzione su Linux).
• <ps-version>: versione di PowerShell (da $PSVersionTable.PSVersion).
• <ps-arch>: architettura del computer del processo di PowerShell.
• <dotnet-version>: la versione segnalata di PowerShell del runtime .NET è in esecuzione (da System.Environment.Version).
• <dotnet-edition>: il tipo di runtime .NET di PowerShell è in esecuzione (attualmente framework o core).

Per esempio:

• win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework è PowerShell 5.1 in esecuzione in Windows 10 Enterprise (build 18312) per x64.
• win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core è PowerShell 6.1.2 in esecuzione nello stesso sistema operativo.
• ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core è PowerShell 6.2.0 in esecuzione in Ubuntu 18.04.

PSScriptAnalyzer include alcuni profili di piattaforma come file JSON. Puoi indirizzare direttamente questi profili integrati nella tua configurazione.

Le piattaforme raggruppate per impostazione predefinita sono:

Altri profili sono disponibili nel repository GitHub .

Puoi anche generare il tuo profilo di piattaforma con il modulo PSCompatibilityCollector.

Le impostazioni di compatibilità includono un elenco delle piattaforme sotto TargetProfiles. Puoi specificare ogni piattaforma target come:

• Un nome di piattaforma (ad esempio, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer lo aggiunge .json e lo cerca nella directory profilo predefinita.
• Un nome file (ad esempio, my_custom_platform.json), che PSScriptAnalyzer cerca nella cartella profilo predefinita.
• Percorso assoluto di un file , ad esempio D:\PowerShellProfiles\TargetMachine.json.

La directory profilo predefinita si trova sotto il modulo PSScriptAnalyzer a $PSScriptRoot/compatibility_profiles (dove $PSScriptRoot qui si riferisce alla directory che contiene PSScriptAnalyzer.psd1).

L'analisi di compatibilità confronta ogni comando che usi sia con un profilo target che con un profilo union. Il profilo unione contiene ogni comando disponibile in qualsiasi profilo nella directory del profilo.

Se un comando non è nel profilo union, la regola presume che sia locale al tuo ambiente e lo ignora. Se un comando è nel profilo unione ma manca in un profilo target, la regola lo segnala come incompatibile con quel target.

Esempio

I seguenti esempi assumono TargetProfiles ( ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core Ubuntu 18.04, PowerShell 6.2).

Non conforme

function Get-OsInfo {
    $os = Get-WmiObject -Class Win32_OperatingSystem
    return $os.Caption
}

Compliant

function Get-OsInfo {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    return $os.Caption
}

Configurare regola

@{
    Rules = @{
        PSUseCompatibleCommands = @{
            Enable = $true
            TargetProfiles = @(
                'ubuntu_x64_18.04_6.1.3_x64_4.0.30319.42000_core'
                'win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework'
                'MyProfile'
                'another_custom_profile_in_the_profiles_directory.json'
                'D:\My Profiles\profile1.json'
            )
            # You can specify commands to not check like this, which also will ignore its parameters:
            IgnoreCommands = @(
                'Install-Module'
            )
        }
    }
}

Soppressione

Come per altre regole, puoi sopprimere la diagnostica di compatibilità dei comandi aggiungendo un attributo di soppressione al param blocco di uno scriptblock.

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands', '')]

Puoi anche sopprimere la regola per comandi specifici:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Start-Service')]

Puoi anche sopprimerlo per parametri specifici:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'Import-Module/FullyQualifiedName')]

Parameters

Enable

Questo parametro controlla se ScriptAnalyzer verifica il codice rispetto a questa regola. Accetta un valore booleano. Per abilitare questa regola, imposta questo parametro a $true. Il valore predefinito è $false.

Profili Target

Questo parametro specifica l'elenco dei profili piattaforma con cui verificare la compatibilità. Accetta una matrice di stringhe. Ogni valore può essere un nome di piattaforma, un nome di file o un percorso assoluto verso un file profilo. Il valore predefinito è @().

ProfileDirPath

Questo parametro controlla la directory che ScriptAnalyzer cerca per i profili per nome e utilizza per generare il profilo union. Accetta una stringa che contiene un percorso assoluto. La posizione predefinita è la compatibility_profiles directory nel modulo PSScriptAnalyzer.

IgnoraCommandi

Questo parametro specifica i comandi da escludere dai controlli di compatibilità. Accetta un array di stringhe di nomi di comando. Il valore predefinito è @().