UseCompatibleCommands

ernstniveau: waarschuwing

Beschrijving

Deze regel detecteert commando's die niet beschikbaar zijn op je beoogde PowerShell-platform.

Een naam in het PowerShell-platform wordt geïdentificeerd in het volgende formaat:

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

Waar:

• <os-name>: de naam van het besturingssysteem waarop PowerShell wordt uitgevoerd. Op Windows is het SKU-nummer inbegrepen. Op Linux is de waarde de naam van de distributie.
• <os-arch>: De machinearchitectuur waarop het besturingssysteem draait (meestal x64).
• <os-version>: De zelfgerapporteerde versie van het besturingssysteem (de distributieversie op Linux).
• <ps-version>: de PowerShell-versie (van $PSVersionTable.PSVersion).
• <ps-arch>: de machinearchitectuur van het PowerShell-proces.
• <dotnet-version>: de gerapporteerde versie van de .NET Runtime PowerShell wordt uitgevoerd (vanaf System.Environment.Version).
• <dotnet-edition>: De .NET Runtime-versie van PowerShell wordt uitgevoerd (momenteel framework of core).

Bijvoorbeeld:

• win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework is PowerShell 5.1 met Windows 10 Enterprise (build 18312) voor x64.
• win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core wordt PowerShell 6.1.2 uitgevoerd op hetzelfde besturingssysteem.
• ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core is PowerShell 6.2.0 uitgevoerd op Ubuntu 18.04.

PSScriptAnalyzer bevat enkele platformprofielen als JSON-bestanden. Je kunt deze ingebouwde profielen direct in je configuratie targeten.

Platformen die standaard zijn gebundeld, zijn:

Andere profielen vindt u in de GitHub-opslagplaats.

Je kunt ook je eigen platformprofiel aanmaken met de PSCompatibilityCollector-module.

Compatibiliteitsinstellingen nemen een lijst van platforms onder TargetProfiles. Je kunt elk doelplatform specificeren als:

• Een platformnaam (bijvoorbeeld ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer voegt .json het toe en zoekt ernaar in de standaard profielmap.
• Een bestandsnaam (bijvoorbeeld my_custom_platform.json), waar PSScriptAnalyzer naar zoekt in de standaard profielmap.
• Een absoluut pad naar een bestand (zoals D:\PowerShellProfiles\TargetMachine.json).

De standaard profielmap bevindt zich onder de PSScriptAnalyzer-module ($PSScriptRoot/compatibility_profileswaar $PSScriptRoot hier wordt verwezen naar de map die ).PSScriptAnalyzer.psd1

De compatibiliteitsanalyse vergelijkt elk commando dat je gebruikt met zowel een doelprofiel als een union-profiel. Het union-profiel bevat elk commando dat beschikbaar is in elk profiel in de profielmap.

Als een commando niet in het union-profiel staat, gaat de regel ervan uit dat het lokaal is in jouw omgeving en negeert het. Als een commando in het union-profiel staat maar ontbreekt in een doelprofiel, markeert de regel het als incompatibel met dat doelwit.

Voorbeeld

De volgende voorbeelden nemen TargetProfiles aan dat het omvat ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core (Ubuntu 18.04, PowerShell 6.2).

Niet conform

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

Compliant

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

Configureerregel

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

Onderdrukking

Net als bij andere regels kun je commandocompatibiliteitsdiagnostiek onderdrukken door een suppressie-attribuut toe te voegen aan het param blok van een scriptblock.

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

Je kunt de regel ook onderdrukken voor specifieke commando's:

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

Je kunt het ook onderdrukken voor specifieke parameters:

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

Parameters

Enable

Deze parameter bepaalt of ScriptAnalyzer de code controleert aan deze regel. Het accepteert een booleaanse waarde. Om deze regel te activeren, zet je deze parameter op $true. De standaardwaarde is $false.

TargetProfiles

Deze parameter specificeert de lijst van platformprofielen waarmee compatibiliteit moet worden gecontroleerd. Het accepteert een lijst van tekenreeksen. Elke waarde kan een platformnaam, een bestandsnaam of een absoluut pad naar een profielbestand zijn. De standaardwaarde is @().

ProfileDirPath

Deze parameter beheert de map die ScriptAnalyzer zoekt naar profielen op naam en gebruikt om het union-profiel te genereren. Het accepteert een string met een absoluut pad. De standaardlocatie is de compatibility_profiles map in de PSScriptAnalyzer-module.

NegeerCommando's

Deze parameter specificeert commando's die worden uitgesloten van compatibiliteitscontroles. Het accepteert een array van commandonaamstrings. De standaardwaarde is @().