Condividi tramite

UseCompatibleCommands

  • Articolo

Livello di gravità: avviso

Descrizione

Questa regola identifica i comandi che non sono disponibili in una piattaforma PowerShell di destinazione.

Una piattaforma PowerShell è identificata da un nome nel formato seguente:

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

Dove:

  • <os-name>: il nome del sistema operativo PowerShell è in esecuzione. In Windows, questo include il numero di SKU. In Linux si tratta del nome della distribuzione.
  • <os-arch>: l'architettura del computer in cui è in esecuzione il sistema operativo (questo è in genere x64).
  • <os-version>: versione auto-segnalata del sistema operativo (in Linux, questa è la versione di distribuzione).
  • <ps-version>: versione di PowerShell (da $PSVersionTable.PSVersion).
  • <ps-arch>: architettura del computer del processo di PowerShell.
  • <dotnet-version>: la versione segnalata di .NET runtime Di PowerShell è in esecuzione (da System.Environment.Version).
  • <dotnet-edition>: il sapore del runtime .NET di PowerShell è in esecuzione in (attualmente framework o core).

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

Alcune piattaforme vengono combinate con PSScriptAnalyzer come file JSON, denominate in questo modo per la destinazione nella configurazione.

Le piattaforme raggruppate per impostazione predefinita sono:

Versione di PowerShell Sistema operativo ID
3.0 Windows Server 2012 win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4,0 Windows Server 2012 R2 win-8_x64_6.3.9600.0_4.0_x64_4.0.30319.42000_framework
5,1 Windows Server 2016 win-8_x64_10.0.14393.0_5.1.14393.2791_x64_4.0.30319.42000_framework
5,1 Windows Server 2019 win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
5,1 Windows 10 1809 (RS5) win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Windows Server 2016 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows Server 2019 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
7.0 Windows Server 2016 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows Server 2019 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_3.1.2_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_7.0.0_x64_3.1.2_core

Altri profili sono disponibili nel repository GitHub.

È anche possibile generare un profilo di piattaforma personalizzato usando il modulo PSCompatibilityCollector.

Le impostazioni del profilo di compatibilità accettano un elenco di piattaforme di destinazione in TargetProfiles. Una piattaforma può essere specificata come:

  • Nome della piattaforma (ad esempio ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), che verrà .json aggiunto alla fine e viene cercato nella directory del profilo predefinita.
  • Nome file (ad esempio my_custom_platform.json), che verrà cercato nella directory del profilo predefinita.
  • Percorso assoluto di un file (ad esempio D:\PowerShellProfiles\TargetMachine.json).

La directory del profilo predefinita è sotto il modulo PSScriptAnalzyer all'indirizzo $PSScriptRoot/compatibility_profiles (dove $PSScriptRoot qui fa riferimento alla directory contenente PSScriptAnalyzer.psd1).

L'analisi della compatibilità confronta un comando usato per un profilo di destinazione e un profilo 'union' (contenente tutti i comandi disponibili in qualsiasi profilo nel profilo dir). Se un comando non è presente nel profilo di unione, si presuppone che venga creato e ignorato in locale. In caso contrario, se un comando è presente nel profilo di unione ma non presente in una destinazione, viene considerato non compatibile con tale destinazione.

Impostazioni di configurazione

Chiave di configurazione Significato Valori accettati Obbligatorio Esempio
Enable Attiva la regola bool ($true/$false) No (impostazione predefinita: $false) $true
TargetProfiles Elenco dei profili di PowerShell di destinazione string[]: percorsi assoluti per i file di profilo o i nomi dei profili nella directory del profilo No (impostazione predefinita: @()) @('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')
ProfileDirPath Posizione per cercare i profili in base al nome e usare per la generazione del profilo di unione string: percorso assoluto del nuovo dir del profilo No (impostazione predefinita per compatibility_profiles la directory nel modulo PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Comandi per ignorare la compatibilità degli script string[]: nomi di comandi da ignorare No (impostazione predefinita: @()) @('Get-ChildItem','Import-Module')

Una configurazione di esempio potrebbe essere simile alla seguente:

@{
    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'
            )
        }
    }
}

Eliminazione degli avvisi

La diagnostica della compatibilità dei comandi può essere eliminata con un attributo nel param blocco di uno scriptblock come con altre regole.

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

La regola può anche essere eliminata solo per i comandi specifici:

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

E anche soppresso solo per i parametri:

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