about_PowerShell_Editions

Breve descrição

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

Descrição longa

A partir do PowerShell 5.1, existem múltiplas edições do PowerShell que correm numa .NET de execução diferente. A partir do PowerShell 6.0, há duas edições do PowerShell:

• Desktop, que corre no .NET Framework. O PowerShell 4 e inferiores, 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 operativos Windows. Esta é a edição original do PowerShell e está incluída na instalação padrão do sistema operacional.
• Core, que corre no .NET Core. O PowerShell 6.0 e posteriores está instalado lado a lado com versões anteriores do PowerShell em edições completas do Windows, algumas edições Windows de pegada reduzida como o Windows Nano Server e o Windows IoT, ou em plataformas não Windows como Linux e macOS.

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

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 que não são fornecidos como parte do Windows (ou seja, módulos que escreve ou instala a partir da galeria), este campo é apenas informativo; O PowerShell não altera o comportamento com base no campo CompatiblePSEditions, mas expõe-o no objeto PSModuleInfo (devolvido por Get-Module) para a sua própria lógica:

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

Desktop
Core

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ções para módulos que vêm como parte do Windows

Para módulos que fazem parte de Windows (ou são instalados como parte de uma função ou funcionalidade), o PowerShell 6.1 e superiores tratam o campo CompatiblePSEditions de forma diferente. Tais módulos encontram-se no diretório de módulos do sistema PowerShell Windows (%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[switch] parâmetro pode ser usado para sobrepor este 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,...

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 utilizas que são afetados pela compatibilidade da edição.

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

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

Assemblies .NET

Se estiver a escrever um módulo binário ou um módulo que incorpore assemblies .NET (DLLs) gerados a partir do código-fonte, deve compilar com .NET Standard e PowerShell Standard para validação de compatibilidade em tempo de compilação de .NET e compatibilidade com a API 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

• about_Automatic_Variables
• Get-Módulo
• Módulo de importação
• Módulos com edições compatíveis do PowerShell