Condividi tramite

Versioni del modulo non definitivo

A partire dalla versione 1.6.0, PowerShellGet e PowerShell Gallery forniscono il supporto per l'assegnazione di tag alle versioni successive alla 1.0.0 come versione preliminare. Prima di questa funzionalità, i pacchetti non definitivi erano limitati ad avere una versione che iniziava con 0. L'obiettivo di queste funzionalità è fornire un maggiore supporto per la convenzione di controllo delle versioni di SemVer v1.0.0 senza interrompere la compatibilità con le versioni precedenti di PowerShell 3 e versioni successive o con le versioni esistenti di PowerShellGet. Questo argomento è incentrato sulle funzionalità specifiche del modulo. Le funzionalità equivalenti per gli script si trovano nell'argomento Versioni non definitive degli script . Utilizzando queste funzionalità, gli editori possono identificare un modulo o uno script come versione 2.5.0-alpha e successivamente rilasciare una versione 2.5.0 pronta per la produzione che sostituisce la versione non definitiva.

A livello generale, le funzionalità del modulo non definitivo includono:

  • L'aggiunta di una stringa non definitiva alla sezione PSData del manifesto del modulo identifica il modulo come versione non definitiva. Quando il modulo viene pubblicato in PowerShell Gallery, questi dati vengono estratti dal manifesto e usati per identificare i pacchetti non definitivi.
  • L'acquisizione di pacchetti non definitivi richiede l'aggiunta -AllowPrerelease di flag ai comandi Find-ModulePowerShellGet , Install-Module, Update-Module, e Save-Module. Se il flag non è specificato, i pacchetti non definitivi non verranno visualizzati.
  • Le versioni dei moduli visualizzate da Find-Module, Get-InstalledModulee in PowerShell Gallery verranno visualizzate come una singola stringa con l'aggiunta della stringa non definitiva, come in 2.5.0-alpha.

I dettagli per le funzionalità sono inclusi di seguito.

Queste modifiche non influiscono sul supporto della versione del modulo incorporato in PowerShell e sono compatibili con PowerShell 3.0, 4.0 e 5.

Identificazione di una versione del modulo come versione preliminare

Il supporto di PowerShellGet per le versioni non definitive richiede l'uso di due campi all'interno del manifesto del modulo:

  • L'oggetto ModuleVersion incluso nel manifesto del modulo deve essere una versione in 3 parti se viene usata una versione non definitiva e deve essere conforme al controllo delle versioni di PowerShell esistente. Il formato della versione sarebbe A.B.C, dove A, B e C sono tutti numeri interi.
  • La stringa di versione preliminare viene specificata nel manifesto del modulo, nella sezione PSData di PrivateData.

Di seguito sono riportati i requisiti dettagliati sulla stringa di Prerelease.

Una sezione di esempio di un manifesto del modulo che definisce un modulo come versione preliminare è simile alla seguente:

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

I requisiti dettagliati per la stringa non definitiva sono:

  • La stringa non definitiva può essere specificata solo quando ModuleVersion è di 3 segmenti per Major.Minor.Build. Questo è in linea con SemVer v1.0.0.
  • Un trattino è il delimitatore tra il numero di build e la stringa di versione non definitiva. Un trattino può essere incluso nella stringa di versione non definitiva solo come primo carattere.
  • La stringa di versione non definitiva può contenere solo caratteri alfanumerici ASCII [0-9A-Za-z-]. È consigliabile iniziare la stringa non definitiva con un carattere alfanumerico, in quanto sarà più facile identificare che si tratta di una versione non definitiva durante la scansione di un elenco di pacchetti.
  • Al momento sono supportate solo le stringhe non definitive di SemVer v1.0.0. La stringa di versione non definitiva non deve contenere un punto o + [.+], consentiti in SemVer 2.0.
  • Esempi di stringhe non definitive supportate sono: -alpha, -alpha1, -BETA -update20171020

Impatto del controllo delle versioni non definitive sull'ordinamento e sulle cartelle di installazione

L'ordinamento cambia quando si usa una versione non definitiva, che è importante quando si pubblica in PowerShell Gallery e quando si installano moduli usando i comandi PowerShellGet. Se la stringa non definitiva viene specificata per due moduli, l'ordinamento si basa sulla parte della stringa che segue il trattino. Quindi, la versione 2.5.0-alpha è inferiore a 2.5.0-beta, che è inferiore a 2.5.0-gamma. Se due moduli hanno lo stesso ModuleVersion e solo uno ha una stringa non definitiva, si presuppone che il modulo senza la stringa non definitiva sia la versione pronta per la produzione e verrà ordinato come versione maggiore rispetto alla versione non definitiva (che include la stringa non definitiva). Ad esempio, quando si confrontano le versioni 2.5.0 e 2.5.0-beta, la versione 2.5.0 sarà considerata la maggiore delle due.

Quando si pubblica in PowerShell Gallery, per impostazione predefinita la versione del modulo da pubblicare deve avere una versione maggiore rispetto a qualsiasi versione pubblicata in precedenza presente in PowerShell Gallery.

Ricerca e acquisizione di pacchetti non definitivi tramite i comandi PowerShellGet

La gestione dei pacchetti non definitivi tramite i comandi PowerShellGet Find-Module, Install-Module, Update-Module e Save-Module richiede l'aggiunta del flag -AllowPrerelease. Se viene specificata -AllowPrerelease, verranno inclusi i pacchetti non definitivi, se presenti. Se -AllowPrerelease flag non viene specificato, i pacchetti non definitivi non verranno visualizzati.

Le uniche eccezioni nei comandi del modulo PowerShellGet sono Get-InstalledModule e alcuni casi con Uninstall-Module.

  • Get-InstalledModule mostrerà sempre automaticamente le informazioni non definitive nella stringa di versione per i moduli.
  • Per impostazione predefinita, Uninstall-Module disinstallerà la versione più recente di un modulo, se non è specificata alcuna versione . Questo comportamento non è cambiato. Tuttavia, se viene specificata una versione non definitiva utilizzando -RequiredVersion, sarà necessario -AllowPrerelease.

Esempi

Si supponga che PowerShell Gallery disponga delle versioni del modulo TestPackage 1.8.0 e 1.9.0-alpha. Se -AllowPrerelease non viene specificato, verrà restituita solo la versione 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...

Per installare una versione non definitiva, specificare sempre -AllowPrerelease. Specificare una stringa di versione non definitiva non è sufficiente.

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

Il comando precedente non è riuscito perché non è stato specificato -AllowPrerelease. L'aggiunta -AllowPrerelease porterà al successo.

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

L'installazione affiancata di versioni di un modulo che differiscono solo per la versione preliminare specificata non è supportata. Quando si installa un modulo usando PowerShellGet, diverse versioni dello stesso modulo vengono installate side-by-side creando un nome di cartella usando ModuleVersion. ModuleVersion, senza la stringa non definitiva, viene utilizzato per il nome della cartella. Se un utente installa MyModule versione 2.5.0-alpha, verrà installato nella MyModule\2.5.0 cartella. Se l'utente installa la versione 2.5.0-beta, la versione 2.5.0-beta sovrascriverà il contenuto della cartella MyModule\2.5.0. Un vantaggio di questo approccio è che non è necessario disinstallare la versione preliminare dopo aver installato la versione pronta per la produzione. L'esempio seguente mostra cosa aspettarsi:

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 rimuoverà l'ultima versione di un modulo quando -RequiredVersion non viene fornito. Se -RequiredVersion è specificato ed è una versione preliminare, è necessario aggiungere -AllowPrerelease al 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...

Altri dettagli

  • Last updated on