Versioni di modulo non definitivePrerelease Module Versions

A partire dalla versione 1.6.0, PowerShellGet e PowerShell Gallery consentono di contrassegnare le versioni successive alla versione 1.0.0 come versioni non definitive.Starting with version 1.6.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. In precedenza, i pacchetti non definitivi potevano avere solo una versione che iniziava con 0.Prior to this feature, prerelease packages were limited to having a version beginning with 0. L'obiettivo di queste funzionalità è quello di offrire un maggior supporto per la convenzione di controllo delle versioni SemVer v1.0.0 senza interrompere la compatibilità con le versioni precedenti con PowerShell versioni 3 e successive o le versioni esistenti di PowerShellGet.The goal of these features is to provide greater support for SemVer v1.0.0 versioning convention without breaking backwards compatibility with PowerShell versions 3 and above, or existing versions of PowerShellGet. Questo argomento illustra le funzionalità specifiche dei moduli.This topic focuses on the module-specific features. Le funzionalità equivalenti per gli script sono descritte nell'argomento Versioni non definitive degli script.The equivalent features for scripts are in the Prerelease Versions of Scripts topic. Usando queste funzionalità, i server di pubblicazione possono identificare un modulo o uno script come versione 2.5.0-alpha e rilasciare in seguito una versione pronta per la produzione 2.5.0 che sostituisce la versione non definitiva.Using these features, publishers can identify a module or script as version 2.5.0-alpha, and later release a production-ready version 2.5.0 that supersedes the prerelease version.

In generale, le funzionalità di modulo non definitivo includono:At a high level, the prerelease module features include:

  • L'aggiunta di una stringa Prerelease alla sezione PSData del manifesto del modulo identifica il modulo come versione non definitiva.Adding a Prerelease string to the PSData section of the module manifest identifies the module as a prerelease version. Quando il modulo viene pubblicato in PowerShell Gallery, i dati vengono estratti dal manifesto e usati per identificare i pacchetti in versione non definitiva.When the module is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease packages.
  • L'acquisizione di pacchetti in versione non definitiva richiede l'aggiunta del flag -AllowPrerelease ai comandi di PowerShellGet Find-Module, Install-Module, Update-Module e Save-Module.Acquiring prerelease packages requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Module, Install-Module, Update-Module, and Save-Module. Se il flag non viene specificato, i pacchetti in versione non definitiva non vengono visualizzati.If the flag is not specified, prerelease packages will not be shown.
  • Le versioni di modulo visualizzate da Find-Module, Get-InstalledModule e in PowerShell Gallery vengono visualizzate come stringa singola con la stringa Prerelease aggiunta alla fine, come nella versione 2.5.0-alpha.Module versions displayed by Find-Module, Get-InstalledModule, and in the PowerShell Gallery will be displayed as a single string with the Prerelease string appended, as in 2.5.0-alpha.

Di seguito sono descritti i dettagli delle funzionalità.Details for the features are included below.

Queste modifiche non influiscono sul supporto della versione di modulo in PowerShell e sono compatibili con PowerShell 3.0, 4.0 e 5.These changes do not affect the module version support that is built into PowerShell, and are compatible with PowerShell 3.0, 4.0, and 5.

Identificazione di una versione di modulo come versione non definitivaIdentifying a module version as a prerelease

Il supporto di PowerShellGet per le versioni non definitive richiede l'uso di due campi all'interno del manifesto del modulo:PowerShellGet support for prerelease versions requires the use of two fields within the Module Manifest:

  • ModuleVersion incluso nel manifesto del modulo deve essere una versione di 3 parti se viene usata una versione non definitiva e deve essere conforme al controllo delle versioni di PowerShell esistente.The ModuleVersion included in the module manifest must be a 3-part version if a prerelease version is used, and must comply with existing PowerShell versioning. Il formato della versione è A.B.C, dove A, B e C sono tutti numeri interi.The version format would be A.B.C, where A, B, and C are all integers.
  • La stringa Prerelease è specificata nel manifesto del modulo, nella sezione PSData di PrivateData.The Prerelease string is specified in the module manifest, in the PSData section of PrivateData.

Di seguito sono descritti nel dettaglio i requisiti della stringa Prerelease.Detailed requirements on the Prerelease string are below.

Una sezione di esempio del manifesto di un modulo che definisce il modulo come versione non definitiva sarà simile alla seguente:An example section of a module manifest that defines a module as a prerelease would look like the following:

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

I requisiti della stringa Prerelease sono i seguenti:The detailed requirements for Prerelease string are:

  • È possibile specificare una stringa Prerelease solo quando ModuleVersion è 3 segmenti per Major.Minor.Build.Prerelease string may only be specified when the ModuleVersion is 3 segments for Major.Minor.Build. Ciò è conforme alla convenzione SemVer v1.0.0.This aligns with SemVer v1.0.0.
  • Un segno meno è il delimitatore tra il numero di build e la stringa Prerelease.A hyphen is the delimiter between the Build number and the Prerelease string. È possibile includere un segno meno nella stringa Prerelease solo come primo carattere.A hyphen may be included in the Prerelease string as the first character, only.
  • La stringa Prerelease può contenere solo caratteri alfanumerici ASCII [0-9A-Za-z-].The Prerelease string may contain only ASCII alphanumerics [0-9A-Za-z-]. È consigliabile fare in modo che la stringa Prerelease inizi con un carattere alfabetico per rendere più semplice l'identificazione di una versione non definitiva durante la ricerca in un elenco di pacchetti.It is a best practice to begin the Prerelease string with an alpha character, as it will be easier to identify that this is a prerelease version when scanning a list of packages.
  • Attualmente sono supportate solo stringhe Prerelease SemVer v1.0.0.Only SemVer v1.0.0 prerelease strings are supported at this time. La stringa Prerelease non deve contenere punti o + [.+], consentiti in SemVer 2.0.Prerelease string must not contain either period or + [.+], which are allowed in SemVer 2.0.
  • Esempi di stringhe Prerelease supportate includono: -alpha, -alpha1, -BETA, -update20171020Examples of supported Prerelease string are: -alpha, -alpha1, -BETA, -update20171020

Impatto del controllo delle versioni non definitive sull'ordinamento e sulle cartelle di installazionePrerelease versioning impact on sort order and installation folders

Quando viene usata una versione non definitiva l'ordinamento viene modificato, un aspetto importante durante la pubblicazione in PowerShell Gallery e l'installazione di moduli con i comandi di PowerShellGet.Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing modules using PowerShellGet commands. Se la stringa Prerelease è specificata per due moduli, l'ordinamento è basato sulla parte di stringa che segue il segno meno.If the Prerelease string is specified for two modules, the sort order is based on the string portion following the hyphen. Di conseguenza, la versione 2.5.0-alpha è precedente alla versione 2.5.0-beta che è a sua volta precedente alla versione 2.5.0-gamma.So, version 2.5.0-alpha is less than 2.5.0-beta, which is less than 2.5.0-gamma. Se due moduli hanno lo stesso ModuleVersion e uno solo include una stringa Prerelease, il modulo senza la stringa Prerelease viene considerato la versione pronta per la produzione e viene ordinato come versione successiva alla versione non definitiva (che include la stringa Prerelease).If two modules have the same ModuleVersion, and only one has a Prerelease string, the module without the Prerelease string is assumed to be the production-ready version and will be sorted as a greater version than the prerelease version (which includes the Prerelease string). Ad esempio, quando viene eseguito il confronto delle versioni 2.5.0 e 2.5.0-beta, la versione 2.5.0 viene considerata la più recente.As an example, when comparing releases 2.5.0 and 2.5.0-beta, the 2.5.0 version will be considered the greater of the two.

Durante la pubblicazione in PowerShell Gallery, per impostazione predefinita la versione del modulo in fase di pubblicazione deve essere successiva a qualsiasi versione pubblicata precedentemente presente in PowerShell Gallery.When publishing to the PowerShell Gallery, by default the version of the module being published must have a greater version than any previously-published version that is in the PowerShell Gallery.

Ricerca e acquisizione di pacchetti in versione non definitiva mediante i comandi di PowerShellGetFinding and acquiring prerelease packages using PowerShellGet commands

L'uso di pacchetti in versione non definitiva con i comandi di PowerShellGet Find-Module, Install-Module, Update-Module e Save-Module richiede l'aggiunta del flag -AllowPrerelease.Dealing with prerelease packages using PowerShellGet Find-Module, Install-Module, Update-Module, and Save-Module commands requires adding the -AllowPrerelease flag. Se il flag -AllowPrerelease è specificato, i pacchetti in versione non definitiva verranno inclusi, se presenti.If -AllowPrerelease is specified, prerelease packages will be included if they are present. Se il flag -AllowPrerelease non è specificato, i pacchetti in versione non definitiva non verranno visualizzati.If -AllowPrerelease flag is not specified, prerelease packages will not be shown.

Le uniche eccezioni nei comandi di modulo di PowerShellGet sono rappresentate da Get-InstalledModule e da alcuni casi di utilizzo di Uninstall-Module.The only exceptions to this in the PowerShellGet module commands are Get-InstalledModule, and some cases with Uninstall-Module.

  • Get-InstalledModule visualizza sempre automaticamente le informazioni di versione non definitiva nella stringa di versione per i moduli.Get-InstalledModule always will automatically show the prerelease information in the version string for modules.
  • Uninstall-Module disinstalla per impostazione predefinita la versione più recente di un modulo, se non è specificata alcuna versione.Uninstall-Module will by default uninstall the most recent version of a module, if no version is specified. Questo comportamento non è stato modificato.That behavior has not changed. Tuttavia, se una versione non definitiva viene specificata usando -RequiredVersion, è necessario specificare -AllowPrerelease.However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required.

EsempiExamples

Si supponga che PowerShell Gallery includa le versioni del modulo TestPackage 1.8.0 e 1.9.0-alpha.Assume the PowerShell Gallery has TestPackage module versions 1.8.0 and 1.9.0-alpha. Se non si specifica -AllowPrerelease, verrà restituita solo la versione 1.8.0.If -AllowPrerelease is not specified, only version 1.8.0 will be returned.

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.To install a prerelease, always specify -AllowPrerelease. Non è sufficiente specificare una stringa di versione non definitiva.Specifying a prerelease version string is not sufficient.

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 riesce perché non viene specificato -AllowPrerelease.The previous command failed because -AllowPrerelease was not specified. L'aggiunta di -AllowPrerelease consentirà di completare correttamente l'operazione.Adding -AllowPrerelease will result in success.

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 side-by-side di versioni di un modulo che si differenziano solo per la versione non definitiva specificata non è supportata.Side-by-side installation of versions of a module that differ only due to the prerelease specified is not supported. Quando si installa un modulo con PowerShellGet, versioni diverse dello stesso modulo vengono installate side-by-side creando un nome di cartella con ModuleVersion.When installing a module using PowerShellGet, different versions of the same module are installed side-by-side by creating a folder name using the ModuleVersion. Per il nome di cartella viene usato ModuleVersion, senza la stringa Prerelease.The ModuleVersion, without the prerelease string, is used for the folder name. Se un utente installa MyModule versione 2.5.0-alpha, il modulo viene installato nella cartella MyModule\2.5.0.If a user installs MyModule version 2.5.0-alpha, it will be installed to the MyModule\2.5.0 folder. Se l'utente installa quindi la versione 2.5.0-beta, la versione 2.5.0-beta sovrascriverà il contenuto della cartella MyModule\2.5.0.If the user then installs 2.5.0-beta, the 2.5.0-beta version will overwrite the contents of the folder MyModule\2.5.0. Uno dei vantaggi di questo approccio è rappresentato dal fatto che non è necessario disinstallare la versione non definitiva dopo aver installato la versione pronta per la produzione.One advantage to this approach is that there is no need to un-install the prerelease version after installing the production-ready version. L'esempio seguente mostra cosa accade:The example below shows what to expect:

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 rimuove la versione più recente di un modulo quando non viene specificato -RequiredVersion.Uninstall-Module will remove the latest version of a module when -RequiredVersion is not supplied. Se -RequiredVersion è specificato e si tratta di una versione non definitiva, è necessario aggiungere -AllowPrerelease al comando.If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command.

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

Altre informazioniMore details