AzCompatibleTypes használata

  • Cikk

Súlyossági szint: Figyelmeztetés

Description

Ez a szabály azonosítja azokat a típusokat, amelyek nem érhetők el (alapértelmezés szerint betöltve) a célzott PowerShell-platformokon.

A PowerShell-platformot egy név azonosítja a következő formátumban:

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

Ahol:

  • <os-name>: A PowerShell operációs rendszer neve fut. Windows rendszeren ez tartalmazza a termékváltozat számát. Linuxon ez a disztribúció neve.
  • <os-arch>: Az operációs rendszer által futtatott gépi architektúra (ez általában x64).
  • <os-version>: Az operációs rendszer saját jelentésű verziója (Linuxon ez a terjesztési verzió).
  • <ps-version>: A PowerShell verziója (forrás $PSVersionTable.PSVersion: ).
  • <ps-arch>: A PowerShell-folyamat gépi architektúrája.
  • <dotnet-version>: A .NET-futtatókörnyezet PowerShell jelentett verziója (a-ból System.Environment.Version) fut.
  • <dotnet-edition>: A .NET-futtatókörnyezeti verzió powershell-verziója (jelenleg framework vagy core) rendszeren fut.

Például:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_frameworkaz x64-hez készült Windows 10 Enterprise (18312-ös build) rendszeren futó PowerShell 5.1.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core az ugyanazon az operációs rendszeren futó PowerShell 6.1.2.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core az Ubuntu 18.04-en futó PowerShell 6.2.0.

Egyes platformok JSON-fájlokként vannak csomagolva a PSScriptAnalyzerhez, így elnevezve a konfigurációban való célzáshoz.

Az alapértelmezés szerint csomagolt platformok a következők:

PowerShell-verzió Operációs rendszer ID (Azonosító)
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

Más profilok a GitHub-adattárban találhatók.

A PSCompatibilityCollector modullal saját platformprofilt is létrehozhat.

A kompatibilitási profil beállításai a célként megcélzott platformok listáját tartalmazzák a területen TargetProfiles. A platform a következőképpen adható meg:

  • Egy platformnév (például ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), amely hozzá lesz .json adva a végéhez, és a rendszer az alapértelmezett profilkönyvtárban keres.
  • Egy fájlnév (például my_custom_platform.json), amelyet a rendszer az alapértelmezett profilkönyvtárban keres.
  • Egy fájl abszolút elérési útja (például D:\PowerShellProfiles\TargetMachine.json).

Az alapértelmezett profilkönyvtár a PSScriptAnalzyer modul $PSScriptRoot/PSCompatibilityCollector/profiles alatt található (ahol $PSScriptRoot itt a következő könyvtárra PSScriptAnalyzer.psd1hivatkozik: ).

A kompatibilitási elemzés egy célprofilhoz és egy "egyesítő" profilhoz használt típust hasonlít össze (amely a profil dir bármely profiljában elérhető összes típust tartalmazza). Ha egy típus nincs jelen az egyesítő profilban, a rendszer azt feltételezi, hogy a rendszer helyileg hozza létre és hagyja figyelmen kívül. Ellenkező esetben, ha egy típus jelen van az egyesítő profilban, de nem található meg egy célban, akkor az nem kompatibilis a célval.

Konfigurációs beállítások

Konfigurációs kulcs Értelmezés Elfogadott értékek Kötelező Példa
Enable A szabály aktiválása bool ($true/$false) Nem (alapértelmezett: $false) $true
TargetProfiles A megcélzandó PowerShell-profilok listája string[]: a profilfájlok vagy profilok neveinek abszolút elérési útjai a profilkönyvtárban Nem (alapértelmezett: @()) @('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 A profilok név szerinti keresésének helye, és az egyesítő profilok létrehozása sztring: az új profildir abszolút elérési útja Nem (alapértelmezés szerint a könyvtár a compatibility_profiles PSScriptAnalyzer modulban C:\Users\me\Documents\pssaCompatProfiles
IgnoreTypes Típusok vagy típusgyorsítók teljes neve a szkriptek kompatibilitásának figyelmen kívül hagyásához sztring[]: figyelmen kívül hagyandó típusok neve Nem (alapértelmezett: @()) @('System.Collections.ArrayList','string')

Egy példakonfiguráció a következőképpen nézhet ki:

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

Másik lehetőségként megadhat egy beállításobjektumot az alábbiak szerint:

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'

Mellőzés

A parancskompatibilitási diagnosztikát letilthatja egy attribútummal a param szkriptblokk blokkjában, mint más szabályok esetén.

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

A szabályt csak bizonyos típusok esetén lehet letiltani:

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

És csak a típustagok esetében is el van tiltva:

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