UseCompatibleCommands

allvarlighetsgrad: Varning

Beskrivning

Denna regel upptäcker kommandon som inte finns tillgängliga på din tillsatta PowerShell-plattform.

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/compatibility_profiles (där $PSScriptRoot här avser katalogen som innehåller PSScriptAnalyzer.psd1).

Kompatibilitetsanalysen jämför varje kommando du använder med både en målprofil och en unionprofil. Unionprofilen innehåller alla kommandon som finns tillgängliga i en profil i profilkatalogen.

Om ett kommando inte finns i unionprofilen antar regeln att det är lokalt i din miljö och ignorerar det. Om ett kommando finns i unionprofilen men saknas i en målprofil, flaggar regeln det som inkompatibelt med det målet.

Exempel

Följande exempel antar TargetProfiles inkluderar ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04, PowerShell 6.2).

Ej överensstämmande

function Get-OsInfo {
    $os = Get-WmiObject -Class Win32_OperatingSystem
    return $os.Caption
}

Godkänd

function Get-OsInfo {
    $os = Get-CimInstance -ClassName Win32_OperatingSystem
    return $os.Caption
}

Konfigurera regel

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

Undertryckande

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

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

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

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

Du kan också undertrycka den för specifika parametrar:

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

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.

IgnoreraKommandon

Denna parameter specificerar kommandon som ska uteslutas från kompatibilitetskontroller. Den accepterar en array av kommandonamnssträngar. Standardvärdet är @().