about_PowerShell_Editions
Descrição breve
Diferentes edições do PowerShell são executadas em diferentes runtimes subjacentes.
Descrição longa
No PowerShell 5.1, há várias edições do PowerShell, cada uma executada em um runtime .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 volume reduzido, 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 seu runtime 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 runtimes 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á executando 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 campo do manifesto CompatiblePSEditions 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 apenas Desktop com compatibilidade:
@{
ModuleVersion = '1.0'
FunctionsToExport = @('Test-MyModule')
CompatiblePSEditions = @('Desktop')
}
Omitir o campo de um manifesto de módulo terá o mesmo efeito que defini-lo como Desktop, já que os CompatiblePSEditions módulos criados antes da introdução desse campo foram escritos implicitamente 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), esse 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
Observação
O CompatiblePSEditions campo do 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 CompatiblePSEditions campo de forma diferente. Esses módulos são encontrados no diretório de módulos do sistema do 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 comporta de acordo.
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 bem-sucedido para um módulo, mas o uso desse módulo corre o risco de encontrar uma incompatibilidade mais tarde; 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ções
Ao escrever um módulo do PowerShell para direcionar edições Desktop 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 as edições; são os cmdlets, módulos e APIs do .NET que você usa que são afetados pela compatibilidade da 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 detectar 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 incorpora DLLs (assemblies do .NET) gerados a partir do código-fonte, deverá compilar no .NET Standard e no PowerShell Standard para validação de compatibilidade em tempo de compilação da compatibilidade da API do .NET e do PowerShell.
Embora essas bibliotecas sejam capazes de verificar alguma compatibilidade em tempo de compilação, elas não serão capazes de detectar possíveis diferenças comportamentais entre as edições. Para isso, você ainda deve escrever testes.
