Condividi tramite

UseCompatibleCommands

  • Articolo

livello di gravità : avviso

Descrizione

Questa regola identifica i comandi non 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 in cui è in esecuzione PowerShell. 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 (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 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.

Alcune piattaforme sono incluse in bundle 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 Pro win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6.2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.14393 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.17763 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6.2 Windows 10.0.18362 win-4_x64_10.0.18362.0_6.2.4_x64_4.0.30319.42000_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.14393 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.17763 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10.0.18362 win-4_x64_10.0.18362.0_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 avrà .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 si trova nel modulo PSScriptAnalzyer in $PSScriptRoot/compatibility_profiles (dove $PSScriptRoot qui fa riferimento alla directory contenente PSScriptAnalyzer.psd1).

L'analisi della compatibilità confronta un comando usato sia con un profilo di destinazione che con un profilo "union" (contenente tutti i comandi disponibili in qualsiasi profilo nel profile 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 incompatibile 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 in cui cercare i profili in base al nome e usare per la generazione del profilo di unione string: percorso assoluto del nuovo profile dir No (impostazione predefinita è compatibility_profiles directory nel modulo PSScriptAnalyzer C:\Users\me\Documents\pssaCompatProfiles
IgnoreCommands Comandi per ignorare la compatibilità di negli script string[]: nomi dei 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'
            )
        }
    }
}

Soppressione

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

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

La regola può anche essere eliminata solo per determinati comandi:

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

E anche soppresso solo per i parametri:

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