UseCompatibleTypes

Tingkat Keparahan : Peringatan

Status default: Dinonaktifkan

Deskripsi

Aturan ini mendeteksi jenis yang tidak tersedia secara default pada platform PowerShell yang ditargetkan.

Nama platform PowerShell menggunakan format berikut:

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

Mana:

  • <os-name>: Nama sistem operasi PowerShell sedang berjalan. Di Windows, nomor SKU disertakan. Di Linux, nilainya adalah nama distribusi.
  • <os-arch>: Arsitektur mesin yang dijalankan sistem operasi (biasanya x64).
  • <os-version>: Versi sistem operasi yang dilaporkan sendiri (versi distribusi di Linux).
  • <ps-version>: Versi PowerShell (dari $PSVersionTable.PSVersion).
  • <ps-arch>: Arsitektur mesin dari proses PowerShell.
  • <dotnet-version>: Versi yang dilaporkan dari PowerShell runtime .NET berjalan pada (dari System.Environment.Version).
  • <dotnet-edition>: PowerShell rasa runtime .NET berjalan pada (saat ini framework atau core).

Misalnya:

  • win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework adalah PowerShell 5.1 yang berjalan di Windows 10 Enterprise (build 18312) untuk x64.
  • win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core adalah PowerShell 6.1.2 yang berjalan pada sistem operasi yang sama.
  • ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core adalah PowerShell 6.2.0 yang berjalan di Ubuntu 18.04.

PSScriptAnalyzer menyertakan beberapa profil platform sebagai file JSON. Anda dapat menargetkan profil bawaan ini langsung di konfigurasi Anda.

Platform yang dibundel secara default adalah:

Versi PowerShell Sistem operasi 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 Server Windows 2016 win-8_x64_10.0.14393.0_5.1.14393.2791_x64_4.0.30319.42000_framework
5.1 Server Windows 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

Profil lain dapat ditemukan direpositori GitHub .

Anda juga dapat membuat profil platform Anda sendiri dengan modul PSCompatibilityCollector.

Pengaturan kompatibilitas mengambil daftar platform di bawah TargetProfiles. Anda dapat menentukan setiap platform target sebagai:

  • Nama platform (misalnya, ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core). PSScriptAnalyzer menambahkan .json dan mencarinya di direktori profil default.
  • Nama file (misalnya, my_custom_platform.json), yang dicari PSScriptAnalyzer di direktori profil default.
  • Jalur absolut ke file (seperti D:\PowerShellProfiles\TargetMachine.json).

Direktori profil default berada di bawah modul PSScriptAnalyzer di $PSScriptRoot/PSCompatibilityCollector/profiles (di mana $PSScriptRoot di sini mengacu pada direktori yang berisi PSScriptAnalyzer.psd1).

Analisis kompatibilitas membandingkan setiap jenis yang Anda gunakan terhadap profil target dan profil gabungan. Profil gabungan berisi setiap jenis yang tersedia di profil apa pun di direktori profil.

Jika jenis tidak ada di profil gabungan, aturan tersebut mengasumsikan bahwa jenis tersebut bersifat lokal untuk lingkungan Anda dan mengabaikannya. Jika jenis ada di profil gabungan tetapi tidak ada dari profil target, aturan menandainya sebagai tidak kompatibel dengan target tersebut.

Contoh

Contoh berikut mengasumsikan TargetProfiles mencakup win-48_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework (Windows 10 Pro, PowerShell 5.1).

Tidak sesuai

System.Management.Automation.SemanticVersion tidak tersedia secara default di Windows PowerShell 5.1, sehingga aturan menandai penggunaan jenis ini untuk profil target tersebut.

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

Sesuai

System.Version tersedia di Windows PowerShell 5.1 dan PowerShell 7, sehingga lulus pemeriksaan kompatibilitas di seluruh target tersebut.

$version = [System.Version]'1.2.3.0'

Mengonfigurasi aturan

Contoh konfigurasi mungkin terlihat seperti:

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

Atau, Anda dapat menyediakan objek pengaturan sebagai berikut:

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'

Parameters

Enable

Parameter ini mengontrol apakah ScriptAnalyzer memeriksa kode terhadap aturan ini. Ini menerima nilai boolean. Untuk mengaktifkan aturan ini, atur parameter ini ke $true. Nilai defaultnya adalah $false.

Profil Target

Parameter ini menentukan daftar profil platform untuk memeriksa kompatibilitas. Ini menerima sekumpulan string. Setiap nilai dapat berupa nama platform, nama file, atau jalur absolut ke file profil. Nilai defaultnya adalah @().

ProfilDirPath

Parameter ini mengontrol direktori yang dicari profil oleh ScriptAnalyzer berdasarkan nama dan digunakan untuk menghasilkan profil gabungan. Ini menerima string yang berisi jalur absolut. Lokasi default adalah compatibility_profiles direktori dalam modul PSScriptAnalyzer.

MengabaikanJenis

Parameter ini menentukan nama lengkap jenis atau akselerator jenis yang akan dikecualikan dari pemeriksaan kompatibilitas. Ini menerima array string nama jenis. Nilai defaultnya adalah @().

Penindasan

Seperti aturan lainnya, Anda dapat menekan diagnostik kompatibilitas jenis dengan menambahkan atribut penekanan ke param blok blok skrip.

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

Anda juga dapat menekan aturan untuk jenis tertentu:

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

Anda juga dapat menekannya untuk anggota jenis tertentu:

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