Share via

about_PowerShell_Editions

  • Artigo

Breve descrição

Diferentes edições do PowerShell são executadas em diferentes tempos de execução subjacentes.

Descrição longa

No PowerShell 5.1, há várias edições do PowerShell que são executadas em um tempo de execução .NET diferente. A partir do PowerShell 6.0, há duas edições do PowerShell:

  • Desktop, que é executado no .NET Framework. O PowerShell 4 e inferior, bem como o PowerShell 5.1, estão disponíveis para edições completas do Windows, como Windows Desktop, Windows Server, Windows Server Core e a maioria dos outros sistemas operacionais Windows. Esta é a edição original do PowerShell e está incluída na instalação padrão do sistema operacional.
  • Core, que é executado no .NET Core. O PowerShell 6.0 e posterior é instalado lado a lado com versões anteriores do PowerShell em edições completas do Windows, algumas edições do Windows com pegada reduzida, como o Windows Nano Server e o Windows IoT, ou em plataformas que não são Windows, como Linux e macOS.

Como a edição do PowerShell corresponde ao seu tempo de execução do .NET, ela é o principal indicador da compatibilidade da API do .NET e do módulo do PowerShell; algumas APIs, tipos ou métodos do .NET não estão disponíveis em ambos os tempos de execução do .NET e isso afeta os scripts e módulos do PowerShell que dependem deles.

A $PSEdition variável automática

No PowerShell 5.1 e superior, você pode descobrir qual edição está sendo executada com a $PSEdition variável automática:

$PSEdition

Core

No PowerShell 4 e inferior, essa variável não existe. $PSEdition ser nulo deve ser tratado como o mesmo que ter o valor Desktop.

Edição em $PSVersionTable

A $PSVersionTable variável automática também tem a propriedade PSEdition no PowerShell 5.1 e superior:

$PSVersionTable

Name                           Value
----                           -----
PSVersion                      7.3.9
PSEdition                      Core
GitCommitId                    7.3.9
OS                             Microsoft Windows 10.0.22621
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

O campo PSEdition tem o mesmo valor que a $PSEdition variável automática.

O CompatiblePSEditions campo de manifesto do módulo

Os módulos do PowerShell podem declarar com quais edições do PowerShell eles são compatíveis usando o CompatiblePSEditions campo do manifesto do módulo.

Por exemplo, um manifesto de módulo declarando compatibilidade com ambas as Desktop edições do Core PowerShell:

@{
    ModuleVersion = '1.0'
    FunctionsToExport = @('Test-MyModule')
    CompatiblePSEditions = @('Desktop', 'Core')
}

Um exemplo de um manifesto de módulo apenas com Desktop compatibilidade:

@{
    ModuleVersion = '1.0'
    FunctionsToExport = @('Test-MyModule')
    CompatiblePSEditions = @('Desktop')
}

Omitir o CompatiblePSEditions campo de um manifesto de módulo terá o mesmo efeito que defini-lo como Desktop, uma vez que os módulos criados antes da introdução deste campo foram implicitamente escritos para esta edição.

Para módulos não enviados como parte do Windows (ou seja, módulos que você escreve ou instala da galeria), este campo é apenas informativo; O PowerShell não altera o CompatiblePSEditions comportamento com base no campo, mas o expõe no PSModuleInfo objeto (retornado por Get-Module) para sua própria lógica:

New-ModuleManifest -Path .\TestModuleWithEdition.psd1 -CompatiblePSEditions Desktop,Core -PowerShellVersion '5.1'
$ModuleInfo = Test-ModuleManifest -Path .\TestModuleWithEdition.psd1
$ModuleInfo.CompatiblePSEditions

Desktop
Core

Nota

O CompatiblePSEditions campo de módulo só é compatível com o PowerShell 5.1 e superior. Incluir esse campo fará com que um módulo seja incompatível com o PowerShell 4 e inferior. Como o campo é puramente informativo, ele pode ser omitido com segurança em versões posteriores do PowerShell.

No PowerShell 6.1, Get-Module -ListAvailable teve seu formatador atualizado para exibir a compatibilidade de edição de cada módulo:

Get-Module -ListAvailable


    Directory: C:\Users\me\Documents\PowerShell\Modules

ModuleType Version    Name                   PSEdition ExportedCommands
---------- -------    ----                   --------- ----------------
Script     1.4.0      Az                     Core,Desk
Script     1.3.1      Az.Accounts            Core,Desk {Disable-AzDataCollection, Disable-AzContextAutosave, E...
Script     1.0.1      Az.Aks                 Core,Desk {Get-AzAks, New-AzAks, Remove-AzAks, Import-AzAksCreden...

...

Script     4.4.0      Pester                 Desk      {Describe, Context, It, Should...}
Script     1.18.0     PSScriptAnalyzer       Desk      {Get-ScriptAnalyzerRule, Invoke-ScriptAnalyzer, Invoke-...
Script     1.0.0      WindowsCompatibility   Core      {Initialize-WinSession, Add-WinFunction, Invoke-WinComm...

Compatibilidade de edição para módulos fornecidos como parte do Windows

Para módulos que vêm como parte do Windows (ou são instalados como parte de uma função ou recurso), o PowerShell 6.1 e superior tratam o campo de CompatiblePSEditions forma diferente. Esses módulos são encontrados no diretório de módulos do sistema Windows PowerShell (%windir%\System\WindowsPowerShell\v1.0\Modules).

Para módulos carregados ou encontrados neste diretório, o PowerShell 6.1 e superior usa o CompatiblePSEditions campo para determinar se o módulo será compatível com a sessão atual e se comportará de acordo.

Quando Import-Module for usado, um módulo sem Core entrada CompatiblePSEditions não será importado e um erro será exibido:

Import-Module BitsTransfer

Import-Module : Module 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1'
 does not support current PowerShell edition 'Core'. Its supported editions are 'Desktop'. Use 'Import-Module
 -SkipEditionCheck' to ignore the compatibility of this module.
At line:1 char:1
+ Import-Module BitsTransfer
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : ResourceUnavailable: (C:\WINDOWS\system32\u2026r\BitsTransfer.psd1:String)
 [Import-Module], InvalidOperationException
+ FullyQualifiedErrorId : Modules_PSEditionNotSupported,Microsoft.PowerShell.Commands.ImportModuleCommand

Quando Get-Module -ListAvailable é usado, os módulos sem Core in CompatiblePSEditions não serão exibidos:

Get-Module -ListAvailable BitsTransfer

# No output

Em ambos os casos, o -SkipEditionCheck parâmetro switch pode ser usado para substituir esse comportamento:

Get-Module -ListAvailable -SkipEditionCheck BitsTransfer


    Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules

ModuleType Version    Name           PSEdition ExportedCommands
---------- -------    ----           --------- ----------------
Manifest   2.0.0.0    BitsTransfer   Desk      {Add-BitsFile, Complete-BitsTransfer, Get-BitsTransfer,...

Aviso

Import-Module -SkipEditionCheck pode parecer bem-sucedido para um módulo, mas usar esse módulo corre o risco de encontrar uma incompatibilidade mais tarde; enquanto o carregamento do módulo inicialmente é bem-sucedido, um comando pode mais tarde chamar uma API incompatível e falhar espontaneamente.

Criação de módulos do PowerShell para compatibilidade cruzada de edições

Ao escrever um módulo do PowerShell para direcionar ambas as Desktop edições do Core PowerShell, há coisas que você pode fazer para garantir a compatibilidade entre edições.

A única maneira verdadeira de confirmar e validar continuamente a compatibilidade, no entanto, é escrever testes para seu script ou módulo e executá-los em todas as versões e edições do PowerShell com as quais você precisa de compatibilidade. Uma estrutura de teste recomendada para isso é o Pester.

Script do PowerShell

Como linguagem, o PowerShell funciona da mesma forma entre edições; são os cmdlets, módulos e APIs .NET que você usa que são afetados pela compatibilidade de edição.

Geralmente, os scripts que funcionam no PowerShell 6.1 e superior funcionarão com o Windows PowerShell 5.1, mas há algumas exceções.

O PSScriptAnalyzer versão 1.18+ tem regras como PSUseCompatibleCommands e PSUseCompatibleTypes que são capazes de detetar o uso possivelmente incompatível de comandos e APIs .NET em scripts do PowerShell.

Assemblies .NET

Se você estiver escrevendo um módulo binário ou um módulo que incorpore assemblies .NET (DLLs) gerados a partir do código-fonte, você deve compilar em relação ao .NET Standard e PowerShell Standard para validação de compatibilidade em tempo de compilação da compatibilidade de API do .NET e PowerShell.

Embora essas bibliotecas sejam capazes de verificar alguma compatibilidade em tempo de compilação, elas não serão capazes de detetar possíveis diferenças comportamentais entre as edições. Para isso, você ainda deve escrever testes.

Consulte também