Partilhar via

Pré-lançamento de Versões do Módulo

  • Artigo

A partir da versão 1.6.0, o PowerShellGet e o Galeria do PowerShell fornecem suporte para versões de identificação superiores a 1.0.0 como pré-lançamento. Antes desta funcionalidade, os pacotes de pré-lançamento limitavam-se a ter uma versão a partir de 0. O objetivo destas funcionalidades é fornecer um maior suporte para a convenção de controlo de versões do SemVer v1.0.0 sem interromper a retrocompatibilidade com as versões 3 e posteriores do PowerShell ou versões existentes do PowerShellGet. Este tópico foca-se nas funcionalidades específicas do módulo. As funcionalidades equivalentes para scripts estão no tópico Versões de Pré-lançamento de Scripts . Com estas funcionalidades, os editores podem identificar um módulo ou script como a versão 2.5.0-alfa e, posteriormente, lançar uma versão 2.5.0 pronta para produção que substitui a versão de pré-lançamento.

A um nível elevado, as funcionalidades do módulo de pré-lançamento incluem:

  • Adicionar uma cadeia de pré-lançamento à secção PSData do manifesto do módulo identifica o módulo como uma versão de pré-lançamento. Quando o módulo é publicado no Galeria do PowerShell, estes dados são extraídos do manifesto e utilizados para identificar pacotes de pré-lançamento.
  • A aquisição de pacotes de pré-lançamento requer a adição -AllowPrerelease de um sinalizador aos comandos Find-Moduledo PowerShellGet , , Install-Modulee Update-ModuleSave-Module. Se o sinalizador não for especificado, os pacotes de pré-lançamento não serão apresentados.
  • As versões do módulo apresentadas por Find-Module, Get-InstalledModulee no Galeria do PowerShell serão apresentadas como uma única cadeia com a cadeia de pré-lançamento anexada, tal como em 2.5.0-alpha.

Os detalhes das funcionalidades estão incluídos abaixo.

Estas alterações não afetam o suporte da versão do módulo incorporado no PowerShell e são compatíveis com o PowerShell 3.0, 4.0 e 5.

Identificar uma versão do módulo como um pré-lançamento

O suporte do PowerShellGet para versões de pré-lançamento requer a utilização de dois campos no Manifesto do Módulo:

  • O ModuleVersion incluído no manifesto do módulo tem de ser uma versão de três partes se for utilizada uma versão de pré-lançamento e tiver de estar em conformidade com o controlo de versões existente do PowerShell. O formato de versão seria A.B.C, onde A, B e C são todos números inteiros.
  • A cadeia pré-lançamento é especificada no manifesto do módulo, na secção PSData de PrivateData.

Os requisitos detalhados na cadeia de pré-lançamento estão abaixo.

Uma secção de exemplo de um manifesto de módulo que define um módulo como pré-lançamento teria o seguinte aspeto:

@{
    ModuleVersion = '2.5.0'
    #---
    PrivateData = @{
        PSData = @{
            Prerelease = 'alpha'
        }
    }
}

Os requisitos detalhados da cadeia de pré-lançamento são:

  • A cadeia de pré-lançamento só pode ser especificada quando moduleVersion é de 3 segmentos para Major.Minor.Build. Isto alinha-se com SemVer v1.0.0.
  • Um hífen é o delimitador entre o número da compilação e a cadeia de pré-lançamento. Um hífen pode ser incluído na cadeia De pré-lançamento como o primeiro caráter, apenas.
  • A cadeia de pré-lançamento pode conter apenas alfanuméricos ASCII [0-9A-Za-z-]. É uma melhor prática iniciar a cadeia de pré-lançamento com um caráter alfa, pois será mais fácil identificar que se trata de uma versão de pré-lançamento ao analisar uma lista de pacotes.
  • Neste momento, só são suportadas cadeias de pré-lançamento semVer v1.0.0. A cadeia de pré-lançamento não pode conter um ponto final ou + [.+], que são permitidos no SemVer 2.0.
  • Exemplos de cadeia de pré-lançamento suportada são: -alpha, -alpha1, -BETA, -update20171020

Impacto no controlo de versões de pré-lançamento nas pastas de ordenação e instalação

A sequência de ordenação muda ao utilizar uma versão de pré-lançamento, o que é importante ao publicar no Galeria do PowerShell e ao instalar módulos com comandos do PowerShellGet. Se a cadeia de pré-lançamento for especificada para dois módulos, a sequência de ordenação baseia-se na parte da cadeia que segue o hífen. Assim, a versão 2.5.0-alfa é inferior a 2.5.0-beta, que é inferior a 2,5,0 gama. Se dois módulos tiverem o mesmo ModuleVersion e apenas um tiver uma cadeia de pré-lançamento, o módulo sem a cadeia de pré-lançamento será considerado a versão pronta para produção e será ordenado como uma versão maior do que a versão de pré-lançamento (que inclui a cadeia de pré-lançamento). Por exemplo, ao comparar as versões 2.5.0 e 2.5.0-beta, a versão 2.5.0 será considerada a maior das duas.

Ao publicar no Galeria do PowerShell, por predefinição, a versão do módulo que está a ser publicado tem de ter uma versão maior do que qualquer versão publicada anteriormente no Galeria do PowerShell.

Localizar e adquirir pacotes de pré-lançamento com comandos do PowerShellGet

Lidar com pacotes de pré-lançamento com o PowerShellGet Find-Module, Install-Module, Update-Module e comandos de Save-Module requer a adição do sinalizador -AllowPrerelease. Se -AllowPrerelease for especificado, os pacotes de pré-lançamento serão incluídos se estiverem presentes. Se -AllowPrerelease sinalizador não for especificado, os pacotes de pré-lançamento não serão apresentados.

As únicas exceções nos comandos do módulo PowerShellGet são Get-InstalledModule e alguns casos com Uninstall-Module.

  • Get-InstalledModule mostrará sempre automaticamente as informações de pré-lançamento na cadeia de versão dos módulos.
  • Uninstall-Module irá, por predefinição, desinstalar a versão mais recente de um módulo, se não for especificada nenhuma versão . Este comportamento não mudou. No entanto, se for especificada uma versão de pré-lançamento com -RequiredVersion, -AllowPrerelease será necessário.

Exemplos

Suponha que o Galeria do PowerShell tem as versões 1.8.0 e 1.9.0-alpha do módulo TestPackage. Se -AllowPrerelease não for especificado, apenas será devolvida a versão 1.8.0.

find-module TestPackage

Version        Name           Repository  Description
-------        ----           ----------  -----------
1.8.0          TestPackage    PSGallery   Package used to validate changes to the PowerShe...

find-module TestPackage -AllowPrerelease

Version        Name           Repository  Description
-------        ----           ----------  -----------
1.9.0-alpha    TestPackage    PSGallery   Package used to validate changes to the PowerShe...

Para instalar uma pré-lançamento, especifique sempre -AllowPrerelease. Especificar uma cadeia de versão de pré-lançamento não é suficiente.

Install-module TestPackage -RequiredVersion 1.9.0-alpha

PackageManagement\Find-Package : No match was found for the specified search criteria and module name 'TestPackage'.
Try Get-PSRepository to see all available registered module repositories.
At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSModule.psm1:1455 char:3
+         PackageManagement\Find-Package @PSBoundParameters | Microsoft ...
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Microsoft.Power...ets.FindPackage:FindPackage) [Find-Package], Exception
    + FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.FindPackage

O comando anterior falhou porque -AllowPrerelease não foi especificado. A adição -AllowPrerelease resultará em êxito.

Install-module TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease
Get-InstalledModule TestPackage

Version         Name          Repository  Description
-------         ----          ----------  -----------
1.9.0-alpha     TestPackage   PSGallery   Package used to validate changes to the PowerShe...

A instalação lado a lado das versões de um módulo que diferem apenas devido à pré-lançamento especificada não é suportada. Ao instalar um módulo com o PowerShellGet, são instaladas versões diferentes do mesmo módulo lado a lado ao criar um nome de pasta com o ModuleVersion. O ModuleVersion, sem a cadeia de pré-lançamento, é utilizado para o nome da pasta. Se um utilizador instalar a versão myModule 2.5.0-alpha, será instalada na MyModule\2.5.0 pasta. Se o utilizador instalar a versão 2.5.0-beta, a versão 2.5.0-beta substituirá os conteúdos da pasta MyModule\2.5.0. Uma das vantagens desta abordagem é que não é necessário anular a instalação da versão de pré-lançamento após a instalação da versão pronta para produção. O exemplo abaixo mostra o que esperar:

C:\windows\system32> Get-InstalledModule TestPackage -AllVersions

Version         Name           Repository  Description
-------         ----           ----------  -----------
1.9.0-alpha     TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.8.0           TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.1.3.2         TestPackage    PSGallery   Package used to validate changes to the PowerShe...

C:\windows\system32> find-module TestPackage -AllowPrerelease

Version        Name            Repository  Description
-------        ----            ----------  -----------
1.9.0-beta     TestPackage     PSGallery   Package used to validate changes to the PowerShe...

C:\windows\system32> Update-Module TestPackage -AllowPrerelease
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions

Version         Name           Repository  Description
-------         ----           ----------  -----------
1.9.0-beta      TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.8.0           TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.1.3.2         TestPackage    PSGallery   Package used to validate changes to the PowerShe...

Uninstall-Module removerá a versão mais recente de um módulo quando -RequiredVersion não for fornecido. Se -RequiredVersion for especificado e for um pré-lançamento, -AllowPrerelease tem de ser adicionado ao comando.

C:\windows\system32> Get-InstalledModule TestPackage -AllVersions

Version         Name           Repository  Description
-------         ----           ----------  -----------
2.0.0-alpha1    TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.9.0-beta      TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.8.0           TestPackage    PSGallery   Package used to validate changes to the PowerShe...
1.1.3.2         TestPackage    PSGallery   Package used to validate changes to the PowerShe...

C:\windows\system32> Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta

Uninstall-Module : The '-AllowPrerelease' parameter must be specified when using the Prerelease string in
MinimumVersion, MaximumVersion, or RequiredVersion.
At line:1 char:1
+ Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Uninstall-Module], ArgumentException
    + FullyQualifiedErrorId : AllowPrereleaseRequiredToUsePrereleaseStringInVersion,Uninstall-Module

C:\windows\system32> Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta -AllowPrerelease
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions

Version         Name          Repository   Description
-------         ----          ----------   -----------
2.0.0-alpha1    TestPackage   PSGallery    Package used to validate changes to the PowerShe...
1.8.0           TestPackage   PSGallery    Package used to validate changes to the PowerShe...
1.1.3.2         TestPackage   PSGallery    Package used to validate changes to the PowerShe...

C:\windows\system32> Uninstall-Module TestPackage
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions

Version         Name          Repository   Description
-------         ----          ----------   -----------
1.8.0           TestPackage   PSGallery    Package used to validate changes to the PowerShe...
1.1.3.2         TestPackage   PSGallery    Package used to validate changes to the PowerShe...

Mais detalhes