Delen via

UseCompatibleTypes

  • Artikel

Ernstniveau: waarschuwing

Description

Met deze regel worden typen geïdentificeerd die niet beschikbaar zijn (standaard geladen) in doel-PowerShell-platforms.

Een PowerShell-platform wordt aangeduid met een naam in de volgende indeling:

<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. In Windows omvat dit het SKU-nummer. In Linux is dit de naam van de distributie.
  • <os-arch>: De machinearchitectuur waarop het besturingssysteem wordt uitgevoerd (dit is meestal x64).
  • <os-version>: De zelf gerapporteerde versie van het besturingssysteem (op Linux is dit de distributieversie).
  • <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 op (van System.Environment.Version).
  • <dotnet-edition>: De .NET-runtime-variant van PowerShell wordt uitgevoerd op (momenteel framework of core).

Bijvoorbeeld:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_frameworkis PowerShell 5.1 uitgevoerd op Windows 10 Enterprise (build 18312) voor x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core is 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.

Sommige platforms worden geleverd met PSScriptAnalyzer als JSON-bestanden, die op deze manier worden genoemd voor targeting in uw configuratie.

Platforms die standaard worden gebundeld, zijn:

PowerShell-versie Besturingssysteem Id
3,0 Windows Server 2012 win-8_x64_6.2.9200.0_3.0_x64_4.0.30319.42000_framework
4,0 Windows Server 2012R2 win-8_x64_6.3.9600.0_4.0_x64_4.0.30319.42000_framework
5.1 Windows Server 2016 win-8_x64_10.0.14393.0_5.1.14393.2791_x64_4.0.30319.42000_framework
5.1 Windows Server 2019 win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
5.1 Windows 10 1809 (RS5) win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework
6,2 Windows Server 2016 win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core
6,2 Windows Server 2019 win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6,2 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core
6,2 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core
7.0 Windows Server 2016 win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core
7.0 Windows Server 2019 win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core
7.0 Windows 10 1809 (RS5) win-4_x64_10.0.17763.0_6.2.4_x64_3.1.2_core
7.0 Ubuntu 18.04 LTS ubuntu_x64_18.04_6.2.4_x64_3.1.2_core

Andere profielen vindt u in de GitHub-opslagplaats.

U kunt ook uw eigen platformprofiel genereren met behulp van de MODULE PSCompatibilityCollector.

Voor de instellingen voor het compatibiliteitsprofiel wordt een lijst met platforms gebruikt om te targeten onder TargetProfiles. Een platform kan worden opgegeven als:

  • Een platformnaam (zoals ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), die aan het einde is .json toegevoegd en waarnaar wordt gezocht in de standaardprofielmap.
  • Een bestandsnaam (zoals my_custom_platform.json), die wordt gezocht naar de in de standaardprofielmap.
  • Een absoluut pad naar een bestand (zoals D:\PowerShellProfiles\TargetMachine.json).

De standaardprofielmap bevindt zich onder de module PSScriptAnalzyer op $PSScriptRoot/PSCompatibilityCollector/profiles (hier $PSScriptRoot verwijst naar de map met PSScriptAnalyzer.psd1).

De compatibiliteitsanalyse vergelijkt een type dat wordt gebruikt met zowel een doelprofiel als een 'union'-profiel (met alle typen die beschikbaar zijn in een profiel in de profieldir). Als een type niet aanwezig is in het samenvoegprofiel, wordt ervan uitgegaan dat het lokaal is gemaakt en genegeerd. Als een type anders aanwezig is in het samenvoegprofiel, maar niet aanwezig is in een doel, wordt het beschouwd als niet compatibel met dat doel.

Configuratie-instellingen

Configuratiesleutel Betekenis Geaccepteerde waarden Verplicht Voorbeeld
Enable De regel activeren bool ($true/$false) Nee (standaard: $false) $true
TargetProfiles De lijst met PowerShell-profielen die u wilt targeten string[]: absolute paden naar profielbestanden of namen van profielen in de profielmap Nee (standaard: @()) @('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')
ProfileDirPath De locatie om profielen te zoeken op naam en te gebruiken voor het genereren van samenvoegprofielen tekenreeks: absoluut pad naar nieuwe profieldir Nee (standaard ingesteld op compatibility_profiles map in PSScriptAnalyzer-module C:\Users\me\Documents\pssaCompatProfiles
IgnoreTypes Volledige namen van typen of typeversnellers om compatibiliteit van in scripts te negeren tekenreeks[]: namen van typen die moeten worden genegeerd Nee (standaard: @()) @('System.Collections.ArrayList','string')

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

Diagnostische gegevens over opdrachtcompatibiliteit kunnen worden onderdrukt met een kenmerk op het param blok van een scriptblock, net als bij andere regels.

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

De regel kan ook alleen worden onderdrukt voor bepaalde typen:

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

En ook alleen onderdrukt voor typeleden:

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