UseCompatibleTypes

livello di gravità : avviso

Descrizione

Questa regola rileva tipi che non sono disponibili di default sulle piattaforme PowerShell di bersaglio.

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/PSCompatibilityCollector/profiles (dove $PSScriptRoot qui si riferisce alla directory che contiene PSScriptAnalyzer.psd1).

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

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

Esempio

I seguenti esempi assumono TargetProfiles includa win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework (Windows 10 Pro, PowerShell 5.1).

Non conforme

System.Management.Automation.SemanticVersion non è disponibile di default in Windows PowerShell 5.1, quindi la regola segnala questo tipo di utilizzo per quel profilo target.

$version = [System.Management.Automation.SemanticVersion]'1.2.3'

Compliant

System.Version è disponibile in Windows PowerShell 5.1 e PowerShell 7, quindi supera i controlli di compatibilità su quei target.

$version = [System.Version]'1.2.3.0'

Configurare regola

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

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

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

Puoi anche sopprimere la regola per tipi specifici:

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

Puoi anche sopprimerlo per membri specifici di tipo:

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

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.

IgnoreTypes

Questo parametro specifica i nomi completi dei tipi o degli acceleratori di tipi da escludere dai controlli di compatibilità. Accetta una serie di stringhe di nomi di tipo. Il valore predefinito è @().