about_PowerShell_Editions
Descrição breve
Diferentes edições do PowerShell são executadas em runtimes subjacentes diferentes.
Descrição longa
No PowerShell 5.1, há várias edições do PowerShell que são executadas em um runtime diferente do .NET. A partir do PowerShell 6.0, há duas edições do PowerShell:
- Área de trabalho, que é executada em .NET Framework. O PowerShell 4 e abaixo, 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 reduzidas do Windows, como Windows Nano Server e Windows IoT, ou em plataformas não Windows, como Linux e macOS.
Como a edição do PowerShell corresponde ao runtime do .NET, ele é o indicador principal da compatibilidade de módulos da API do .NET e do PowerShell; algumas APIs do .NET, tipos ou métodos não estão disponíveis em runtimes do .NET e isso afeta 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 você está executando com a $PSEdition variável automática:
$PSEdition
Core
No PowerShell 4 e abaixo, essa variável não existe. $PSEdition ser nulo deve ser tratado como o mesmo que ter o valor Desktop.
Edição no $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 campo de manifesto do CompatiblePSEditions módulo
Os módulos do PowerShell podem declarar quais edições do PowerShell são compatíveis com o uso do CompatiblePSEditions campo do manifesto do módulo.
Por exemplo, um manifesto de módulo declarando compatibilidade com as Desktop edições e Core do PowerShell:
@{
ModuleVersion = '1.0'
FunctionsToExport = @('Test-MyModule')
CompatiblePSEditions = @('Desktop', 'Core')
}
Um exemplo de um manifesto de módulo com apenas Desktop compatibilidade:
@{
ModuleVersion = '1.0'
FunctionsToExport = @('Test-MyModule')
CompatiblePSEditions = @('Desktop')
}
A omissão do CompatiblePSEditions campo de um manifesto de módulo terá o mesmo efeito que defini-lo como , uma vez que Desktopos módulos criados antes desse campo foram introduzidos implicitamente para esta edição.
Para módulos não enviados como parte do Windows (ou seja, módulos que você escreve ou instala por meio da galeria), esse campo é somente 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
Observação
O CompatiblePSEditions campo de módulo só é compatível com o PowerShell 5.1 e superior. A inclusão desse campo fará com que um módulo seja incompatível com o PowerShell 4 e abaixo. 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 seu formatador foi 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 que são 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 CompatiblePSEditions campo de forma diferente. Esses módulos são encontrados no diretório Windows PowerShell módulos do sistema (%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á adequadamente.
Quando Import-Module for usado, um módulo sem Core in 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 for 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 ter êxito para um módulo, mas o uso desse módulo corre o risco de encontrar uma incompatibilidade posteriormente; enquanto o carregamento do módulo é inicialmente bem-sucedido, um comando pode chamar posteriormente uma API incompatível e falhar espontaneamente.
Criação de módulos do PowerShell para compatibilidade cruzada de edição
Ao escrever um módulo do PowerShell para direcionar as Desktop edições e Core do PowerShell, há coisas que você pode fazer para garantir a compatibilidade entre edições.
No entanto, a única maneira verdadeira de confirmar e validar continuamente a compatibilidade é 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 um idioma, o PowerShell funciona da mesma forma entre as 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 Windows PowerShell 5.1, mas há algumas exceções.
PSScriptAnalyzer versão 1.18+ tem regras como PSUseCompatibleCommands e PSUseCompatibleTypes que são capazes de detectar o uso possivelmente incompatível de comandos e APIs do .NET em scripts do PowerShell.
Assemblies .NET
Se você estiver escrevendo um módulo binário ou um módulo que incorpora assemblies .NET (DLLs) gerados a partir do código-fonte, você deverá compilar no .NET Standard e no PowerShell Standard para validação de compatibilidade em tempo de compilação da compatibilidade do .NET e da compatibilidade da API do PowerShell.
Embora essas bibliotecas sejam capazes de marcar alguma compatibilidade em tempo de compilação, elas não poderão capturar possíveis diferenças comportamentais entre as edições. Para isso, você ainda deve escrever testes.