UseCompatibleTypes

Articolo
12/12/2024

livello di gravità : avviso

Descrizione

Questa regola identifica i tipi non disponibili (caricati per impostazione predefinita) nelle piattaforme di 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/PSCompatibilityCollector/profiles (dove $PSScriptRoot qui fa riferimento alla directory contenente PSScriptAnalyzer.psd1).

L'analisi della compatibilità confronta un tipo usato sia con un profilo di destinazione che con un profilo "union" (contenente tutti i tipi disponibili in qualsiasi profilo nel profile dir). Se un tipo non è presente nel profilo di unione, si presuppone che venga creato e ignorato in locale. In caso contrario, se un tipo è 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`
`IgnoreTypes`	Nomi completi di tipi o acceleratori di tipi per ignorare la compatibilità di negli script	string[]: nomi di tipi da ignorare	No (impostazione predefinita: `@()`)	`@('System.Collections.ArrayList','string')`

Una configurazione di esempio potrebbe essere simile alla seguente:

@{
    Rules = @{
        PSUseCompatibleTypes = @{
            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 types to not check like this, which will also ignore methods and members on it:
            IgnoreTypes = @(
                'System.IO.Compression.ZipFile'
            )
        }
    }
}

In alternativa, è possibile fornire un oggetto impostazioni come indicato di seguito:

PS> $settings = @{
      Rules = @{
        PSUseCompatibleTypes = @{
          Enable = $true
          TargetProfiles = @('win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework')
        }
      }
}
PS> Invoke-ScriptAnalyzer -Settings $settings -ScriptDefinition "[System.Management.Automation.SemanticVersion]'1.18.0-rc1'"

RuleName                Severity     ScriptName Line  Message
--------                --------     ---------- ----  -------
PSUseCompatibleTypes    Warning                 1     The type 'System.Management.Automation.SemanticVersion' is
                                                      not available by default in PowerShell version
                                                      '5.1.17763.316' on platform 'Microsoft Windows 10 Pro'

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('PSUseCompatibleTypes', '')]

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

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleTypes',
    'System.Management.Automation.Security.SystemPolicy')]

E anche soppresso solo per i membri di tipo:

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseCompatibleCommands',
    'System.Management.Automation.LanguagePrimitives/ConvertTypeNameToPSTypeName')]

Condividi tramite

UseCompatibleTypes

Descrizione

Impostazioni di configurazione

Soppressione

Commenti e suggerimenti

Risorse aggiuntive