UseCompatibleTypes

Artykuł
10/31/2024

poziom ważności: ostrzeżenie

Opis

Ta reguła identyfikuje typy, które nie są dostępne (domyślnie ładowane) na docelowych platformach programu PowerShell.

Platforma programu PowerShell jest identyfikowana przez nazwę w następującym formacie:

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

Gdzie:

<os-name>: nazwa systemu operacyjnego PowerShell jest uruchomiona. W systemie Windows obejmuje to numer jednostki SKU. W systemie Linux jest to nazwa dystrybucji.
<os-arch>: Architektura maszyny, na którym działa system operacyjny (zazwyczaj jest to x64).
<os-version>: zgłaszana przez siebie wersja systemu operacyjnego (w systemie Linux jest to wersja dystrybucji).
<ps-version>: wersja programu PowerShell (z $PSVersionTable.PSVersion).
<ps-arch>: architektura maszyny procesu programu PowerShell.
<dotnet-version>: zgłoszona wersja środowiska uruchomieniowego platformy .NET programu PowerShell jest uruchomiona (z System.Environment.Version).
<dotnet-edition>: w środowisku uruchomieniowym platformy .NET jest uruchomiony program PowerShell (obecnie framework lub core).

Na przykład:

win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework to program PowerShell 5.1 uruchomiony w systemie Windows 10 Enterprise (kompilacja 18312) dla wersji x64.
win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core program PowerShell 6.1.2 działa w tym samym systemie operacyjnym.
ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core to program PowerShell 6.2.0 uruchomiony w systemie Ubuntu 18.04.

Niektóre platformy są powiązane z plikiem PSScriptAnalyzer jako pliki JSON, nazwane w ten sposób do określania wartości docelowych w konfiguracji.

Platformy dołączone domyślnie to:

Wersja programu PowerShell	System operacyjny	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 2012 R2	`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 Pro	`win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework`
6.2	Ubuntu 18.04 LTS	`ubuntu_x64_18.04_6.2.4_x64_4.0.30319.42000_core`
6.2	Windows 10.0.14393	`win-8_x64_10.0.14393.0_6.2.4_x64_4.0.30319.42000_core`
6.2	Windows 10.0.17763	`win-8_x64_10.0.17763.0_6.2.4_x64_4.0.30319.42000_core`
6.2	Windows 10.0.18362	`win-4_x64_10.0.18362.0_6.2.4_x64_4.0.30319.42000_core`
7.0	Ubuntu 18.04 LTS	`ubuntu_x64_18.04_7.0.0_x64_3.1.2_core`
7.0	Windows 10.0.14393	`win-8_x64_10.0.14393.0_7.0.0_x64_3.1.2_core`
7.0	Windows 10.0.17763	`win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core`
7.0	Windows 10.0.18362	`win-4_x64_10.0.18362.0_7.0.0_x64_3.1.2_core`

Inne profile można znaleźć w repozytorium usługi GitHub .

Możesz również wygenerować własny profil platformy przy użyciu modułu PSCompatibilityCollector.

Ustawienia profilu zgodności zawierają listę platform docelowych w obszarze TargetProfiles. Platformę można określić jako:

Nazwa platformy (na przykład ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), która będzie miała .json dodana na końcu i jest wyszukiwana w domyślnym katalogu profilów.
Nazwa pliku (na przykład my_custom_platform.json), która będzie wyszukiwana w domyślnym katalogu profilu.
Ścieżka bezwzględna do pliku (na przykład D:\PowerShellProfiles\TargetMachine.json).

Domyślny katalog profilu znajduje się w module PSScriptAnalzyer w $PSScriptRoot/PSCompatibilityCollector/profiles (gdzie $PSScriptRoot tutaj odnosi się do katalogu zawierającego PSScriptAnalyzer.psd1).

Analiza zgodności porównuje typ używany zarówno do profilu docelowego, jak i profilu "unii" (zawierający wszystkie typy dostępne w dowolnym profilu w dir profilu). Jeśli typ nie istnieje w profilu unii, przyjmuje się, że jest tworzony lokalnie i ignorowany. W przeciwnym razie, jeśli typ jest obecny w profilu unii, ale nie istnieje w obiekcie docelowym, jest uważany za niezgodny z tym celem.

Ustawienia konfiguracji

Klucz konfiguracji	Znaczenie	Zaakceptowane wartości	Obowiązkowy	Przykład
`Enable`	Aktywuje regułę	bool (`$true`/`$false`)	Nie (ustawienie domyślne: `$false`)	`$true`
`TargetProfiles`	Lista profilów programu PowerShell do miejsca docelowego	string[]: ścieżki bezwzględne do plików profilu lub nazw profilów w katalogu profilu	Nie (ustawienie domyślne: `@()`)	`@('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`	Lokalizacja do wyszukiwania profilów według nazwy i użycia dla generowania profilu unii	ciąg: ścieżka bezwzględna do nowego dir profilu	Nie (domyślnie jest to katalog `compatibility_profiles` w module PSScriptAnalyzer	`C:\Users\me\Documents\pssaCompatProfiles`
`IgnoreTypes`	Pełne nazwy typów lub akceleratorów typów w celu ignorowania zgodności skryptów	string[]: nazwy typów do zignorowania	Nie (ustawienie domyślne: `@()`)	`@('System.Collections.ArrayList','string')`

Przykładowa konfiguracja może wyglądać następująco:

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

Alternatywnie można podać obiekt ustawień w następujący sposób:

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'

Tłumienie

Diagnostyka zgodności poleceń może zostać pominięta za pomocą atrybutu w bloku param bloku skryptu, tak jak w przypadku innych reguł.

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

Regułę można również pominąć tylko dla określonych typów:

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

Pomijane są również tylko elementy członkowskie typu:

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

Udostępnij za pośrednictwem

UseCompatibleTypes

Opis

Ustawienia konfiguracji

Tłumienie

Opinia

Dodatkowe zasoby