Prerelease-moduleversies

Vanaf versie 1.6.0 bieden PowerShellGet en de PowerShell Gallery ondersteuning voor taggen van versies die groter zijn dan 1.0.0 als voorlopige versie. Vóór deze functie waren prereleasepakketten beperkt tot een versie vanaf 0. Het doel van deze functies is om meer ondersteuning te bieden voor semVer v1.0.0 versieconventie zonder achterwaartse compatibiliteit met PowerShell-versies 3 en hoger of bestaande versies van PowerShellGet te verbreken. Dit onderwerp is gericht op de modulespecifieke functies. De equivalente functies voor scripts bevinden zich in het onderwerp Prerelease-versies van scripts . Met deze functies kunnen uitgevers een module of script identificeren als versie 2.5.0-alpha en later een productieklare versie 2.5.0 vrijgeven die de voorlopige versie vervangt.

Op hoog niveau zijn de functies van de prerelease-module onder andere:

  • Als u een Prerelease-tekenreeks toevoegt aan de SECTIE PSData van het modulemanifest, wordt de module geïdentificeerd als een voorlopige versie. Wanneer de module wordt gepubliceerd naar de PowerShell Gallery, worden deze gegevens uit het manifest geëxtraheerd en gebruikt om prereleasepakketten te identificeren.
  • Voor het verkrijgen van prereleasepakketten moet u een vlag toevoegen -AllowPrerelease aan de PowerShellGet-opdrachtenFind-Module, Install-Moduleen Update-ModuleSave-Module. Als de vlag niet is opgegeven, worden prereleasepakketten niet weergegeven.
  • Moduleversies die worden weergegeven door Find-Module, Get-InstalledModuleen in de PowerShell Gallery worden weergegeven als één tekenreeks waaraan de Prerelease-tekenreeks is toegevoegd, zoals in 2.5.0-alfa.

Hieronder vindt u meer informatie over de functies.

Deze wijzigingen hebben geen invloed op de moduleversieondersteuning die is ingebouwd in PowerShell en zijn compatibel met PowerShell 3.0, 4.0 en 5.

Een moduleversie identificeren als een voorlopige versie

PowerShellGet-ondersteuning voor prereleaseversies vereist het gebruik van twee velden in het modulemanifest:

  • De ModuleVersion die in het modulemanifest is opgenomen, moet een driedelige versie zijn als er een voorlopige versie wordt gebruikt en moet voldoen aan bestaande Versiebeheer van PowerShell. De versie-indeling zou A.B.C zijn, waarbij A, B en C allemaal gehele getallen zijn.
  • De prereleasetekenreeks wordt opgegeven in het modulemanifest, in de sectie PSData van PrivateData.

Gedetailleerde vereisten voor de Prerelease-tekenreeks zijn hieronder.

Een voorbeeldsectie van een modulemanifest dat een module definieert als een prerelease, ziet er als volgt uit:

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

De gedetailleerde vereisten voor prereleasetekenreeks zijn:

  • Prereleasetekenreeks kan alleen worden opgegeven wanneer de ModuleVersion 3 segmenten is voor Major.Minor.Build. Dit komt overeen met SemVer v1.0.0.
  • Een afbreekstreepje is het scheidingsteken tussen het buildnummer en de Prerelease-tekenreeks. Een afbreekstreepje kan alleen als eerste teken worden opgenomen in de tekenreeks Prerelease.
  • De tekenreeks Prerelease mag alleen ASCII alfanumerics [0-9A-Za-z-]. Het is een best practice om de Prerelease-tekenreeks met een alfateken te starten, omdat het gemakkelijker is om te identificeren dat dit een voorlopige versie is bij het scannen van een lijst met pakketten.
  • Alleen SemVer v1.0.0 prereleasetekenreeksen worden op dit moment ondersteund. Prereleasetekenreeks mag geen punt of + [.+] bevatten, die zijn toegestaan in SemVer 2.0.
  • Voorbeelden van ondersteunde Prerelease-tekenreeks zijn: -alpha, -alpha1, -BETA, -update20171020

Prerelease versiebeheer van invloed op sorteervolgorde en installatiemappen

Sorteervolgordewijzigingen bij het gebruik van een voorlopige versie, wat belangrijk is bij het publiceren naar de PowerShell Gallery en bij het installeren van modules met behulp van PowerShellGet-opdrachten. Als de tekenreeks Prerelease is opgegeven voor twee modules, wordt de sorteervolgorde gebaseerd op het tekenreeksgedeelte na het afbreekstreepje. Dus versie 2.5.0-alfa is kleiner dan 2.5.0-bèta, die kleiner is dan 2.5.0-gamma. Als twee modules dezelfde ModuleVersion hebben en er slechts één een Prerelease-tekenreeks heeft, wordt ervan uitgegaan dat de module zonder de Prerelease-tekenreeks de versie is die gereed is voor productie en wordt gesorteerd als een grotere versie dan de prerelease-versie (inclusief de Prerelease-tekenreeks). Als u bijvoorbeeld releases 2.5.0 en 2.5.0 beta vergelijkt, wordt de 2.5.0-versie beschouwd als de grotere van de twee.

Wanneer u publiceert naar de PowerShell Gallery, moet standaard de versie van de module die wordt gepubliceerd, een grotere versie hebben dan een eerder gepubliceerde versie in de PowerShell Gallery.

Prerelease-pakketten zoeken en verkrijgen met behulp van PowerShellGet-opdrachten

Voor het omgaan met prereleasepakketten met behulp van PowerShellGet Find-Module, Install-Module, Update-Module en Save-Module-opdrachten moet de vlag -AllowPrerelease worden toegevoegd. Als -AllowPrerelease is opgegeven, worden prereleasepakketten opgenomen als ze aanwezig zijn. Als de vlag -AllowPrerelease niet is opgegeven, worden prereleasepakketten niet weergegeven.

De enige uitzonderingen hierop in de PowerShellGet-moduleopdrachten zijn Get-InstalledModule en sommige gevallen met Uninstall-Module.

  • Get-InstalledModule altijd automatisch de informatie over de voorlopige versie in de versiereeks voor modules weergeeft.
  • Uninstall-Module verwijdert standaard de meest recente versie van een module als er geen versie is opgegeven. Dat gedrag is niet veranderd. Als echter een prerelease-versie is opgegeven met behulp van -RequiredVersion, -AllowPrerelease is vereist.

Voorbeelden

Stel dat de PowerShell Gallery TestPackage-moduleversies 1.8.0 en 1.9.0-alfa heeft. Als -AllowPrerelease dit niet is opgegeven, wordt alleen versie 1.8.0 geretourneerd.

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...

Als u een prerelease wilt installeren, geeft u altijd -AllowPrerelease op. Het opgeven van een voorlopige versietekenreeks is niet voldoende.

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

De vorige opdracht is mislukt omdat -AllowPrerelease niet is opgegeven. Het toevoegen -AllowPrerelease leidt tot succes.

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...

Naast elkaar installeren van versies van een module die alleen verschillen vanwege de opgegeven prerelease, wordt niet ondersteund. Wanneer u een module installeert met Behulp van PowerShellGet, worden verschillende versies van dezelfde module naast elkaar geïnstalleerd door een mapnaam te maken met behulp van ModuleVersion. De ModuleVersion, zonder de tekenreeks prerelease, wordt gebruikt voor de mapnaam. Als een gebruiker MyModule versie 2.5.0-alpha installeert, wordt deze geïnstalleerd in de MyModule\2.5.0 map. Als de gebruiker vervolgens 2.5.0-beta installeert, wordt de inhoud van de map MyModule\2.5.0overschreven door de 2.5.0-bètaversie. Een voordeel van deze benadering is dat de voorlopige versie niet hoeft te worden geïnstalleerd nadat de productieklare versie is geïnstalleerd. In het onderstaande voorbeeld ziet u wat u kunt verwachten:

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 verwijdert de nieuwste versie van een module wanneer -RequiredVersion niet is opgegeven. Als -RequiredVersion is opgegeven en een prerelease is, moet -AllowPrerelease worden toegevoegd aan de opdracht.

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...

Meer informatie