UseCompatibleTypes

allvarlighetsgrad: Varning

Beskrivning

Denna regel upptäcker typer som inte är tillgängliga som standard på dina riktade PowerShell-plattformar.

Ett namn i PowerShell-plattformen identifieras 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å. På Windows ingår SKU-numret. På Linux är värdet namnet på distributionen.
• <os-arch>: Maskinarkitekturen som operativsystemet körs på (vanligtvis x64).
• <os-version>: Den självrapporterade versionen av operativsystemet (distributionsversionen på Linux).
• <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.

PSScriptAnalyzer inkluderar vissa plattformsprofiler som JSON-filer. Du kan rikta in dig på dessa inbyggda profiler direkt i din konfiguration.

Plattformar som paketeras som standard är:

Andra profiler finns på GitHub-lagringsplatsen.

Du kan också skapa din egen plattformsprofil med PSCompatibilityCollector-modulen.

Kompatibilitetsinställningar tar en lista över plattformar under TargetProfiles. Du kan ange varje målplattform som:

• Ett plattformsnamn (till exempel ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer lägger till .json och söker efter den i standardprofilkatalogen.
• Ett filnamn (till exempel my_custom_platform.json), som PSScriptAnalyzer söker efter i standardprofilkatalogen.
• En absolut sökväg till en fil (som D:\PowerShellProfiles\TargetMachine.json).

Standardprofilkatalogen finns under PSScriptAnalyzer-modulen på $PSScriptRoot/PSCompatibilityCollector/profiles (där $PSScriptRoot här avser katalogen som innehåller PSScriptAnalyzer.psd1).

Kompatibilitetsanalysen jämför varje typ du använder med både en målprofil och en unionprofil. Fackföreningsprofilen innehåller alla typer som finns tillgängliga i vilken profil som helst i profilkatalogen.

Om en typ inte finns i unionprofilen antar regeln att den är lokal för din miljö och ignorerar den. Om en typ finns i unionsprofilen men saknas i en målprofil, markerar regeln den som inkompatibel med det målet.

Exempel

Följande exempel antar TargetProfiles inkluderar win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework (Windows 10 Pro, PowerShell 5.1).

Ej överensstämmande

System.Management.Automation.SemanticVersion är inte tillgängligt som standard i Windows PowerShell 5.1, så regeln flaggar denna typ av användning för den målprofilen.

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

Godkänd

System.Version finns i Windows PowerShell 5.1 och PowerShell 7, så den klarar kompatibilitetskontroller över dessa mål.

$version = [System.Version]'1.2.3.0'

Konfigurera regel

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

Precis som med andra regler kan du undertrycka typkompatibilitetsdiagnostik genom att lägga till ett suppressionsattribut till blocket param i ett skriptblock.

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

Du kan också undertrycka regeln för specifika typer:

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

Du kan också undertrycka den för specifika typer av medlemmar:

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

Parameters

Enable

Denna parameter styr om ScriptAnalyzer kontrollerar koden mot denna regel. Den accepterar ett boolesk värde. För att aktivera denna regel, sätt denna parameter till $true. Standardvärdet är $false.

TargetProfiles

Denna parameter specificerar listan över plattformsprofiler som ska kontrolleras mot kompatibilitet. Den accepterar en matris med strängar. Varje värde kan vara ett plattformsnamn, ett filnamn eller en absolut väg till en profilfil. Standardvärdet är @().

ProfileDirPath

Denna parameter styr katalogen som ScriptAnalyzer söker efter profiler efter namn och använder för att generera unionprofilen. Den accepterar en sträng som innehåller en absolut väg. Standardplatsen är compatibility_profiles katalogen i PSScriptAnalyzer-modulen.

IgnoreTypes

Denna parameter specificerar fullständiga namn på typ- eller typacceleratorer för att utesluta från kompatibilitetskontroller. Den accepterar en array av typnamnssträngar. Standardvärdet är @().