about_PowerShell_Editions

Descrição curta

Diferentes edições do PowerShell são executadas em runtimes subjacentes diferentes.

Descrição longa

Do 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:

• Desktop, que é executado no .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 seu runtime do .NET, ele é o principal indicador de compatibilidade da API do .NET e do módulo 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 variável automática $PSEdition:

$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 variável automática $PSVersionTable também tem 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 variável automática $PSEdition.

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 campo CompatiblePSEditions do manifesto do módulo.

Por exemplo, um manifesto de módulo declarando compatibilidade com edições Desktop 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')
}

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

Para módulos não enviados como parte do Windows (ou seja, módulos que você grava ou instala por meio da galeria), esse campo é somente informativo; O PowerShell não altera o comportamento com base no campo CompatiblePSEditions, mas o expõe no objeto PSModuleInfo (retornado por Get-Module) para 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ção para módulos que são enviados 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 CompatiblePSEditions 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 campo CompatiblePSEditions para determinar se o módulo será compatível com a sessão atual e se comporta adequadamente.

Quando Import-Module for usado, um módulo sem Core no 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 no CompatiblePSEditions não serão exibidos:

Get-Module -ListAvailable BitsTransfer

# No output

Em ambos os casos, o parâmetro de opção -SkipEditionCheck 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,...

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

Ao escrever um módulo do PowerShell para direcionar as edições Desktop 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 é gravar 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 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 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 do .NET

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

Embora essas bibliotecas possam 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.

Consulte também

• about_Automatic_Variables
• get-module
• import-module
• módulos com edições compatíveis do PowerShell