UseCompatibleTypes

ernstniveau: waarschuwing

Beschrijving

Deze regel detecteert types die standaard niet beschikbaar zijn op je beoogde PowerShell-platforms.

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/PSCompatibilityCollector/profileswaar $PSScriptRoot hier wordt verwezen naar de map die ).PSScriptAnalyzer.psd1

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

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

Voorbeeld

De volgende voorbeelden gaan ervan uit dat TargetProfileswin-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework omvat (Windows 10 Pro, PowerShell 5.1).

Niet conform

System.Management.Automation.SemanticVersion is standaard niet beschikbaar in Windows PowerShell 5.1, dus de regel markeert dit type gebruik voor dat doelprofiel.

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

Compliant

System.Version is beschikbaar in Windows PowerShell 5.1 en PowerShell 7, dus het doorstaat compatibiliteitscontroles over die doelen.

$version = [System.Version]'1.2.3.0'

Configureerregel

Een voorbeeldconfiguratie kan er als volgt uitzien:

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

U kunt ook als volgt een instellingenobject opgeven:

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'

Onderdrukking

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

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

Je kunt de regel ook onderdrukken voor specifieke types:

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

Je kunt het ook onderdrukken voor specifieke type leden:

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

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.

IgnoreTypes

Deze parameter specificeert de volledige namen van types of typeversnellers om compatibiliteitscontroles uit te sluiten. Het accepteert een array van typenaamstrings. De standaardwaarde is @().