about_PowerShell_Editions
Descrição breve
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 diferente do .NET. A partir do PowerShell 6.0, há duas edições do PowerShell:
- Desktop, que é executado no .NET Framework. O PowerShell 4 e versões posteriores, 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 espaço reduzido, como o Windows Nano Server e o Windows IoT, ou em plataformas que não sejam do Windows, como Linux e macOS.
Como a edição do PowerShell corresponde ao seu tempo de execução do .NET, ela é o principal indicador de 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á 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 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 são compatíveis usando o campo do manifesto CompatiblePSEditions
do módulo.
Por exemplo, um manifesto de módulo declarando compatibilidade com ambas e Desktop
Core
edições 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')
}
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 desse campo foram escritos implicitamente para esta edição.
Para módulos não fornecidos como parte do Windows (ou seja, módulos que você escreve ou instala a partir da galeria), esse campo é apenas informativo; O PowerShell não altera o comportamento com base no CompatiblePSEditions
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 versões posteriores. 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 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 posteriormente 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 e Core
edições 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 é 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 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.
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, deverá compilar em relação ao .NET Standard e ao PowerShell Standard para validação de compatibilidade em tempo de compilação da compatibilidade com o .NET e a API 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.
Confira também
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de