Partilhar via

Módulos Portáteis

O Windows PowerShell foi escrito para do .NET Framework, enquanto o PowerShell Core foi escrito para .NET Core. Os módulos portáteis são módulos que funcionam no Windows PowerShell e no PowerShell Core. Embora o .NET Framework e o .NET Core sejam altamente compatíveis, há diferenças nas APIs disponíveis entre os dois. Também há diferenças nas APIs disponíveis no Windows PowerShell e no PowerShell Core. Os módulos destinados a serem usados em ambos os ambientes precisam estar cientes dessas diferenças.

Portabilidade de um módulo existente

Portando um PSSnapIn

Os SnapIns do PowerShell não são suportados no PowerShell Core. No entanto, é trivial converter um PSSnapIn em um módulo do PowerShell. Normalmente, o código de registro PSSnapIn está em um único arquivo de origem de uma classe que deriva de PSSnapIn. Remova este arquivo de origem da compilação; não é mais necessário.

Use o New-ModuleManifest para criar um novo manifesto de módulo que substitua a necessidade do código de registo PSSnapIn. Alguns valores do PSSnapIn (como Description) podem ser reutilizados no manifesto do módulo.

A propriedade RootModule no manifesto do módulo deve ser definida como o nome do assembly (.dll) que implementa os cmdlets.

O .NET Portability Analyzer (também conhecido como APIPort)

Para portar módulos escritos para que o Windows PowerShell funcione com o PowerShell Core, comece com o .NET Portability Analyzer. Execute essa ferramenta em seu assembly compilado para determinar se as APIs do .NET usadas no módulo são compatíveis com o .NET Framework, o .NET Core e outros tempos de execução do .NET. A ferramenta sugere APIs alternativas, caso existam. Caso contrário, talvez seja necessário adicionar verificações de tempo de execução e restringir recursos não disponíveis em tempos de execução específicos.

Criando um novo módulo

Se estiver criando um novo módulo, a recomendação é usar o .NET CLI.

Instalando o modelo de módulo padrão do PowerShell

Depois que a CLI do .NET estiver instalada, instale uma biblioteca de modelos para gerar um módulo simples do PowerShell. O módulo será compatível com Windows PowerShell, PowerShell Core, Windows, Linux e macOS.

O exemplo a seguir mostra como instalar o modelo:

dotnet new install Microsoft.PowerShell.Standard.Module.Template

The following template packages will be installed:
   Microsoft.PowerShell.Standard.Module.Template

Success: Microsoft.PowerShell.Standard.Module.Template::0.1.3 installed the following templates:
Template Name               Short Name  Language  Tags
--------------------------  ----------  --------  -------------------------
PowerShell Standard Module  psmodule    [C#]      Library/PowerShell/Module

Criando um novo projeto de módulo

Depois que o modelo for instalado, você poderá criar um novo projeto de módulo do PowerShell usando esse modelo. Neste exemplo, o módulo de exemplo é chamado 'myModule'.

PS> mkdir myModule

    Directory: C:\Users\Steve

Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 8/3/2018 2:41 PM myModule

PS> cd myModule
PS C:\Users\Steve\myModule> dotnet new psmodule
The template "PowerShell Standard Module" was created successfully.

Processing post-creation actions...
Restoring  C:\Users\Steve\myModule\myModule.csproj:
  Determining projects to restore...
  Restored C:\Users\Steve\myModule\myModule.csproj (in 184 ms).
Restore succeeded.

Construindo o módulo

Use comandos padrão da CLI do .NET para criar o projeto.

dotnet build

PS C:\Users\Steve\myModule> dotnet build
MSBuild version 17.6.3+07e294721 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  PowerShellPG -> C:\Users\Steve\myModule\bin\Debug\netstandard2.0\myModule.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:02.36

Testando o módulo

Depois de criar o módulo, você pode importá-lo e executar o cmdlet de exemplo.

Import-Module .\bin\Debug\netstandard2.0\myModule.dll
Test-SampleCmdlet -?
Test-SampleCmdlet -FavoriteNumber 7 -FavoritePet Cat

NAME
    Test-SampleCmdlet

SYNTAX
    Test-SampleCmdlet [-FavoriteNumber] <int> [[-FavoritePet] {Cat | Dog | Horse}] [<CommonParameters>]


ALIASES
    None


REMARKS
    None


FavoriteNumber FavoritePet
-------------- -----------
             7 Cat

Depurando o módulo

Para obter um guia sobre como configurar o Visual Studio Code para depurar o módulo, consulte Como usar o Visual Studio Code para depurar cmdlets compilados.

Tecnologias de apoio

As seções a seguir descrevem em detalhes algumas das tecnologias usadas por este modelo.

Biblioteca padrão do .NET

do .NET Standard é uma especificação formal de APIs do .NET que estão disponíveis em todas as implementações do .NET. Código gerido que tem como alvo o .NET Standard é compatível com as versões do .NET Framework e do .NET Core que são compatíveis com essa versão do .NET Standard.

Observação

Embora uma API possa existir no .NET Standard, a implementação da API no .NET Core pode lançar um PlatformNotSupportedException no tempo de execução, portanto, para verificar a compatibilidade com o Windows PowerShell e o PowerShell Core, a prática recomendada é executar testes para seu módulo em ambos os ambientes. Execute também testes em Linux e macOS se o seu módulo se destinar a ser multiplataforma.

O direcionamento do .NET Standard ajuda a garantir que, à medida que o módulo evolui, APIs incompatíveis não sejam acidentalmente introduzidas no módulo. As incompatibilidades são descobertas em tempo de compilação em vez de tempo de execução.

No entanto, não é necessário direcionar o .NET Standard para que um módulo funcione com o Windows PowerShell e o PowerShell Core, desde que você use APIs compatíveis. A linguagem intermediária (IL) é compatível entre os dois tempos de execução. Você pode direcionar o .NET Framework 4.6.1, que é compatível com o .NET Standard 2.0. Se você não usar APIs fora do .NET Standard 2.0, seu módulo funcionará com o PowerShell Core 6 sem recompilação.

Biblioteca padrão do PowerShell

A biblioteca de do PowerShell Standard é uma especificação formal das APIs do PowerShell disponíveis em todas as versões do PowerShell maiores ou iguais à versão desse padrão.

Por exemplo, do PowerShell Standard 5.1 é compatível com o Windows PowerShell 5.1 e o PowerShell Core 6.0 ou mais recente.

Recomendamos que você compile seu módulo usando a Biblioteca Padrão do PowerShell. A biblioteca garante que as APIs estejam disponíveis e implementadas no Windows PowerShell e no PowerShell Core 6. O PowerShell Standard destina-se a ser sempre compatível com versões futuras. Um módulo criado usando a Biblioteca Padrão do PowerShell 5.1 sempre será compatível com versões futuras do PowerShell.

Manifesto do módulo

Indicando a compatibilidade com o Windows PowerShell e o PowerShell Core

Depois de validar que seu módulo funciona com o Windows PowerShell e o PowerShell Core, o manifesto do módulo deve indicar explicitamente a compatibilidade usando a propriedade CompatiblePSEditions. Um valor de Desktop significa que o módulo é compatível com o Windows PowerShell, enquanto um valor de Core significa que o módulo é compatível com o PowerShell Core. Incluir Desktop e Core significa que o módulo é compatível com o Windows PowerShell e o PowerShell Core.

Observação

Core não significa automaticamente que o módulo é compatível com Windows, Linux e macOS. A propriedade CompatiblePSEditions foi introduzida no PowerShell v5. Os manifestos de módulo que usam a propriedade CompatiblePSEditions não são carregados em versões anteriores ao PowerShell v5.

Indicando a compatibilidade do sistema operacional

Primeiro, valide se o seu módulo funciona em Linux e macOS. Em seguida, indique a compatibilidade com esses sistemas operacionais no manifesto do módulo. Isso torna mais fácil para os usuários encontrarem seu módulo para seu sistema operacional quando publicado no PowerShell Gallery.

Dentro do manifesto do módulo, a propriedade PrivateData tem uma subpropriedade PSData. A propriedade Tags opcional do PSData usa uma matriz de valores que aparecem na Galeria do PowerShell. A Galeria do PowerShell oferece suporte aos seguintes valores de compatibilidade:

Etiqueta Descrição
PSEdition_Core Compatível com o PowerShell Core 6
PSEdition_Desktop Compatível com o Windows PowerShell
Mac OS Compatível com Windows
Aplicações Linux Compatível com Linux (sem distro específico)
macOS Compatível com macOS

Exemplo:

@{
    GUID = "4ae9fd46-338a-459c-8186-07f910774cb8"
    Author = "Microsoft Corporation"
    CompanyName = "Microsoft Corporation"
    Copyright = "(C) Microsoft Corporation. All rights reserved."
    HelpInfoUri = "https://go.microsoft.com/fwlink/?linkid=855962"
    ModuleVersion = "1.2.4"
    PowerShellVersion = "3.0"
    ClrVersion = "4.0"
    RootModule = "PackageManagement.psm1"
    Description = 'PackageManagement (a.k.a. OneGet) is a new way to discover and install software packages from around the web.
 it's a manager or multiplexer of existing package managers (also called package providers) that unifies Windows package management with a single Windows PowerShell interface. With PackageManagement, you can do the following.
  - Manage a list of software repositories in which packages can be searched, acquired and installed
  - Discover software packages
  - Seamlessly install, uninstall, and inventory packages from one or more software repositories'

    CmdletsToExport = @(
        'Find-Package',
        'Get-Package',
        'Get-PackageProvider',
        'Get-PackageSource',
        'Install-Package',
        'Import-PackageProvider'
        'Find-PackageProvider'
        'Install-PackageProvider'
        'Register-PackageSource',
        'Set-PackageSource',
        'Unregister-PackageSource',
        'Uninstall-Package'
        'Save-Package'
    )

    FormatsToProcess  = @('PackageManagement.format.ps1xml')

    PrivateData = @{
        PSData = @{
            Tags = @('PackageManagement', 'PSEdition_Core', 'PSEdition_Desktop', 'Windows', 'Linux', 'macOS')
            ProjectUri = 'https://oneget.org'
        }
    }
}

Dependência de bibliotecas nativas

Os módulos destinados ao uso em diferentes sistemas operacionais ou arquiteturas de processador podem depender de uma biblioteca gerenciada que depende de algumas bibliotecas nativas.

Antes do PowerShell 7, seria necessário ter um código personalizado para carregar a dll nativa apropriada para que a biblioteca gerenciada possa localizá-la corretamente.

Com o PowerShell 7, os binários nativos a serem carregados são pesquisados em subpastas dentro do local da biblioteca gerenciada seguindo um subconjunto da notação Catálogo RID do .NET.

managed.dll folder
    |
    |--- 'win-x64' folder
    |       |--- native.dll
    |
    |--- 'win-x86' folder
    |       |--- native.dll
    |
    |--- 'win-arm' folder
    |       |--- native.dll
    |
    |--- 'win-arm64' folder
    |       |--- native.dll
    |
    |--- 'linux-x64' folder
    |       |--- native.so
    |
    |--- 'linux-x86' folder
    |       |--- native.so
    |
    |--- 'linux-arm' folder
    |       |--- native.so
    |
    |--- 'linux-arm64' folder
    |       |--- native.so
    |
    |--- 'osx-x64' folder
    |       |--- native.dylib
  • Last updated on