UseCompatibleTypes

allvarlighetsgrad: Varning

Beskrivning

Den här regeln identifierar typer som inte är tillgängliga (inlästa som standard) i målbaserade PowerShell-plattformar.

En PowerShell-plattform identifieras med ett namn i följande format:

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

Var:

• <os-name>: Namnet på operativsystemet PowerShell körs på. I Windows innehåller detta SKU-numret. I Linux är det här namnet på distributionen.
• <os-arch>: Datorarkitekturen som operativsystemet körs på (detta är vanligtvis x64).
• <os-version>: Den självrapporterade versionen av operativsystemet (i Linux är det här distributionsversionen).
• <ps-version>: PowerShell-versionen (från $PSVersionTable.PSVersion).
• <ps-arch>: Datorarkitekturen för PowerShell-processen.
• <dotnet-version>: Den rapporterade versionen av .NET Runtime PowerShell körs på (från System.Environment.Version).
• <dotnet-edition>: .NET-körningssmaken PowerShell körs på (för närvarande framework eller core).

Till exempel:

• win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework körs PowerShell 5.1 på Windows 10 Enterprise (version 18312) för x64.
• win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core körs PowerShell 6.1.2 på samma operativsystem.
• ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core körs PowerShell 6.2.0 på Ubuntu 18.04.

Vissa plattformar levereras med PSScriptAnalyzer som JSON-filer, namngivna på det här sättet för målinriktning i konfigurationen.

Plattformar som paketeras som standard är:

Andra profiler finns på GitHub-lagringsplatsen.

Du kan också generera en egen plattformsprofil med hjälp av modulen PSCompatibilityCollector.

Inställningarna för kompatibilitetsprofilen tar en lista över plattformar som ska riktas under TargetProfiles. En plattform kan anges som:

• Ett plattformsnamn (till exempel ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), som kommer att ha .json lagts till i slutet och söks efter i standardprofilkatalogen.
• Ett filnamn (till exempel my_custom_platform.json), som söks efter i standardprofilkatalogen.
• En absolut sökväg till en fil (som D:\PowerShellProfiles\TargetMachine.json).

Standardprofilkatalogen finns under MODULen PSScriptAnalzyer på $PSScriptRoot/PSCompatibilityCollector/profiles (där $PSScriptRoot här refererar till katalogen som innehåller PSScriptAnalyzer.psd1).

Kompatibilitetsanalysen jämför en typ som används med både en målprofil och en "union"-profil (som innehåller alla typer som är tillgängliga i alla profil i profildir). Om en typ inte finns i unionsprofilen antas den vara lokalt skapad och ignorerad. Annars, om en typ finns i unionsprofilen men inte finns i ett mål, anses den vara inkompatibel med det målet.

Konfigurationsinställningar

En exempelkonfiguration kan se ut så här:

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

Du kan också ange ett inställningsobjekt på följande sätt:

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'

Undertryckande

Kommandokompatibilitetsdiagnostik kan ignoreras med ett attribut på param-blocket i en scriptblock som med andra regler.

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

Regeln kan också ignoreras endast för vissa typer:

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

Och undertrycks endast för typmedlemmar:

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