UseCompatibleTypes

Artigo
10/31/2024

Nível de gravidade: aviso

Descrição

Essa regra identifica tipos que não estão disponíveis (carregados por padrão) em plataformas direcionadas do PowerShell.

Uma plataforma do PowerShell é identificada por um nome no seguinte formato:

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

Onde:

<os-name>: o nome do sistema operacional no qual o PowerShell está em execução. No Windows, isso inclui o número de SKU. No Linux, esse é o nome da distribuição.
<os-arch>: a arquitetura do computador em que o sistema operacional está em execução (geralmente é x64).
<os-version>: a versão autorre reportada do sistema operacional (no Linux, esta é a versão de distribuição).
<ps-version>: a versão do PowerShell (de $PSVersionTable.PSVersion).
<ps-arch>: a arquitetura do computador do processo do PowerShell.
<dotnet-version>: a versão relatada do PowerShell do runtime do .NET está em execução (de System.Environment.Version).
<dotnet-edition>: o powershell do tipo de runtime do .NET está em execução (atualmente framework ou core).

Por exemplo:

win-4_x64_10.0.18312.0_5.1.18312.1000_x64_4.0.30319.42000_framework é o PowerShell 5.1 em execução no Windows 10 Enterprise (build 18312) para x64.
win-4_x64_10.0.18312.0_6.1.2_x64_4.0.30319.42000_core é o PowerShell 6.1.2 em execução no mesmo sistema operacional.
ubuntu_x64_18.04_6.2.0_x64_4.0.30319.42000_core é o PowerShell 6.2.0 em execução no Ubuntu 18.04.

Algumas plataformas vêm agrupadas com PSScriptAnalyzer como arquivos JSON, nomeados dessa forma para direcionamento em sua configuração.

As plataformas agrupadas por padrão são:

Versão do PowerShell	Sistema Operacional	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`

Outros perfis podem ser encontrados no repositório GitHub.

Você também pode gerar seu próprio perfil de plataforma usando o módulo PSCompatibilityCollector.

As configurações de perfil de compatibilidade levam uma lista de plataformas a serem direcionadas em TargetProfiles. Uma plataforma pode ser especificada como:

Um nome de plataforma (como ubuntu_x64_18.04_6.1.1_x64_4.0.30319.42000_core), que terá .json adicionado ao final e é pesquisado no diretório de perfil padrão.
Um nome de arquivo (como my_custom_platform.json), que será pesquisado no diretório de perfil padrão.
Um caminho absoluto para um arquivo (como D:\PowerShellProfiles\TargetMachine.json).

O diretório de perfil padrão está no módulo PSScriptAnalzyer em $PSScriptRoot/PSCompatibilityCollector/profiles (em que $PSScriptRoot aqui se refere ao diretório que contém PSScriptAnalyzer.psd1).

A análise de compatibilidade compara um tipo usado com um perfil de destino e um perfil 'union' (contendo todos os tipos disponíveis em qualquer perfil no dir do perfil). Se um tipo não estiver presente no perfil de união, ele será considerado criado localmente e ignorado. Caso contrário, se um tipo estiver presente no perfil de união, mas não estiver presente em um destino, ele será considerado incompatível com esse destino.

Configurações

Chave de configuração	Significado	Valores aceitos	Obrigatório	Exemplo
`Enable`	Ativa a regra	bool (`$true`/`$false`)	Não (padrão: `$false`)	`$true`
`TargetProfiles`	A lista de perfis do PowerShell a serem direcionados	string[]: caminhos absolutos para arquivos de perfil ou nomes de perfis no diretório de perfil	Não (padrão: `@()`)	`@('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`	O local para pesquisar perfis por nome e usar para geração de perfil de união	cadeia de caracteres: caminho absoluto para o novo dir de perfil	Não (padrão para `compatibility_profiles` diretório no módulo PSScriptAnalyzer	`C:\Users\me\Documents\pssaCompatProfiles`
`IgnoreTypes`	Nomes completos de tipos ou aceleradores de tipo para ignorar a compatibilidade de scripts	string[]: nomes de tipos a serem ignorados	Não (padrão: `@()`)	`@('System.Collections.ArrayList','string')`

Uma configuração de exemplo pode ser semelhante a:

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

Como alternativa, você pode fornecer um objeto de configurações da seguinte maneira:

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'

Supressão

O diagnóstico de compatibilidade de comando pode ser suprimido com um atributo no bloco param de um scriptblock como com outras regras.

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

A regra também pode ser suprimida somente para tipos específicos:

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

E também suprimido apenas para membros do tipo:

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

Compartilhar via

UseCompatibleTypes

Descrição

Configurações

Supressão

Comentários

Recursos adicionais