Versiones preliminares de scriptsPrerelease versions of scripts


A partir de la versión 1.6.0, PowerShellGet y la Galería de PowerShell admiten el etiquetado de versiones posteriores a 1.0.0 como versión preliminar.Starting with version 1.6.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Antes de esta característica, los paquetes de versión preliminar se limitaban a tener una versión que comenzaba por 0.Prior to this feature, prerelease packages were limited to having a version beginning with 0. El objetivo de estas características es proporcionar mayor compatibilidad con la convención de control de versiones SemVer v1.0.0 sin interrumpir la compatibilidad con versiones anteriores de PowerShell (versión 3 y superiores) o con versiones existentes de 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. Este tema se centra en las características específicas de los scripts.This topic focuses on the script-specific features. Las características equivalentes de los módulos se encuentran en el tema Versiones preliminares de módulos.The equivalent features for modules are in the Prerelease Module Versions topic. Con estas características, los publicadores pueden identificar un script como versión 2.5.0-alpha y, posteriormente, publicar una versión 2.5.0 lista para producción que sustituya a la versión preliminar.Using these features, publishers can identify a script as version 2.5.0-alpha, and later release a production-ready version 2.5.0 that supersedes the prerelease version.

En general, las características de los scripts de versión preliminar incluyen:At a high level, the prerelease script features include:

  • Se agrega un sufijo PrereleaseString a la cadena de versión en el manifiesto del script.Adding a PrereleaseString suffix to the version string in the script manifest. Cuando los scripts se publican en la Galería de PowerShell, estos datos se extraen del manifiesto y se usan para identificar paquetes de versión preliminar.When the scripts is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease packages.
  • La adquisición de paquetes de versión preliminar exige agregar la marca -AllowPrerelease a los comandos de PowerShellGet Find-Script, Install-Script, Update-Script y Save-Script.Acquiring prerelease packages requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Script, Install-Script, Update-Script, and Save-Script. Si no se especifica la marca, no se muestran los paquetes de versión preliminar.If the flag is not specified, prerelease packages will not be shown.
  • Las versiones de script mostradas por Find-Script, Get-InstalledScript y en la Galería de PowerShell se muestran con el sufijo PrereleaseString, como en 2.5.0-alpha.Script versions displayed by Find-Script, Get-InstalledScript, and in the PowerShell Gallery will be displayed with the PrereleaseString, as in 2.5.0-alpha.

A continuación se incluyen detalles de las características.Details for the features are included below.

Identificación de una versión de script como versión preliminarIdentifying a script version as a prerelease

La compatibilidad de PowerShellGet con las versiones preliminares resulta más sencilla con los scripts que con los módulos.PowerShellGet support for prerelease versions is easier for scripts than modules. El control de versiones de script solo es compatible con PowerShellGet, por lo que no hay ningún problema de compatibilidad debido a la adición de la cadena de versión preliminar.Script versioning is only supported by PowerShellGet, so there are no compatibility issues caused by adding the prerelease string. Para identificar un script de la Galería de PowerShell como una versión preliminar, agregue un sufijo de versión preliminar a una cadena de versión con un formato correcto en los metadatos del script.To identify a script in the PowerShell Gallery as a prerelease, add a prerelease suffix to a properly-formatted version string in the script metadata.

El aspecto de una sección de ejemplo de un manifiesto de script con una versión preliminar sería similar al siguiente:An example section of a script manifest with a prerelease version would look like the following:

<#PSScriptInfo

.VERSION 3.2.1-alpha12

.GUID

...

#>

Para usar un sufijo de versión preliminar, la cadena de versión debe cumplir los siguientes requisitos:To use a prerelease suffix, the version string must meet the following requirements:

  • Solo se puede especificar un sufijo de versión preliminar si la versión tiene tres segmentos para Major.Minor.Build.A prerelease suffix may only be specified when the Version is 3 segments for Major.Minor.Build. Esto se alinea con SemVer v1.0.0.This aligns with SemVer v1.0.0
  • El sufijo de versión preliminar es una cadena que comienza con un guión y puede contener caracteres alfanuméricos ASCII [0-9A-Za-z-].The prerelease suffix is a string which begins with a hyphen, and may contain ASCII alphanumerics [0-9A-Za-z-]
  • De momento solo se admiten las cadenas de versión preliminar de SemVer v1.0.0, por lo que el sufijo de versión preliminar no debe contener ni punto ni + [.+], que sí se permiten en SemVer 2.0.Only SemVer v1.0.0 prerelease strings are supported at this time, so the prerelease suffix must not contain either period or + [.+], which are allowed in SemVer 2.0
  • Ejemplos de cadenas admitidas con sufijo PrereleaseString son: -alpha, -alpha1, -BETA, -update20171020.Examples of supported PrereleaseString strings are: -alpha, -alpha1, -BETA, -update20171020

Impacto del control de versiones preliminares en las carpetas de instalación y en el criterio de ordenaciónPrerelease versioning impact on sort order and installation folders

El criterio de ordenación cambia cuando se usa una versión preliminar, lo que es importante si se publica en la Galería de PowerShell y si se instalan scripts con comandos de PowerShellGet.Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing scripts using PowerShellGet commands. Si hay dos versiones de script con el mismo número de versión, el criterio de ordenación se basa en la parte de la cadena que sigue al guión.If two scripts versions with the version number exist, the sort order is based on the string portion following the hyphen. Por lo tanto, la versión 2.5.0-alpha es menor que 2.5.0-beta, que es menor que 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. Si hay dos scripts con el mismo número de versión y solo uno tiene un sufijo PrereleaseString, se da por hecho que el script sin el sufijo de versión preliminar es la versión lista para producción y se ordena como una versión mayor que la versión preliminar.If two scripts have the same version number, and only one has a PrereleaseString, the script without the prerelease suffix is assumed to be the production-ready version and will be sorted as a greater version than the prerelease version. Por ejemplo, al comparar las versiones 2.5.0 y 2.5.0-beta, la versión 2.5.0 se considera la mayor.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.

Al publicar en la Galería de PowerShell, de forma predeterminada, la versión del script que se va a publicar debe ser mayor que cualquier versión publicada previamente que se encuentre en la Galería de PowerShell.When publishing to the PowerShell Gallery, by default the version of the script being published must have a greater version than any previously-published version that is in the PowerShell Gallery. Un publicador puede actualizar la versión 2.5.0-alpha con 2.5.0-beta o con 2.5.0 (sin sufijo de versión preliminar).A publisher may update version 2.5.0-alpha with 2.5.0-beta, or with 2.5.0 (with no prerelease suffix).

Búsqueda y adquisición de paquetes de versión preliminar mediante comandos de PowerShellGetFinding and acquiring prerelease packages using PowerShellGet commands

Para trabajar con paquetes de versión preliminar mediante los comandos de PowerShellGet Find-Script, Install-Script, Update-Script y Save-Script es necesario agregar la marca -AllowPrerelease.Dealing with prerelease packages using PowerShellGet Find-Script, Install-Script, Update-Script, and Save-Script commands requires adding the -AllowPrerelease flag. Si se especifica -AllowPrerelease, se incluyen los paquetes de versión preliminar, siempre que estén presentes.If -AllowPrerelease is specified, prerelease packages will be included if they are present. Si no se especifica la marca -AllowPrerelease, no se muestran los paquetes de versión preliminar.If -AllowPrerelease flag is not specified, prerelease packages will not be shown.

Las únicas excepciones a esto en los comandos de script de PowerShellGet son Get-InstalledScript y algunos casos con Uninstall-Script.The only exceptions to this in the PowerShellGet script commands are Get-InstalledScript, and some cases with Uninstall-Script.

  • Get-InstalledScript siempre muestra automáticamente la información de versión preliminar en la cadena de versión, si está presente.Get-InstalledScript always will automatically show the prerelease information in the version string if it is present.
  • Uninstall-Script desinstala de forma predeterminada la versión más reciente de un script, si no hay ninguna versión especificada.Uninstall-Script will by default uninstall the most recent version of a script, if no version is specified. Ese comportamiento no ha cambiado.That behavior has not changed. Pero, si se especifica una versión preliminar con -RequiredVersion, se necesitará -AllowPrerelease.However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required.

EjemplosExamples

# Assume the PowerShell Gallery has TestPackage versions 1.8.0 and 1.9.0-alpha.
# If -AllowPrerelease is not specified, only version 1.8.0 will be returned.
C:\windows\system32> Find-Script TestPackage

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

C:\windows\system32> Find-Script TestPackage -AllowPrerelease

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

# To install a prerelease, you must specify -AllowPrerelease. Specifying a prerelease version string is not sufficient.

C:\windows\system32> Install-Script TestPackage -RequiredVersion 1.9.0-alpha

PackageManagement\Find-Package : No match was found for the specified search criteria and script name 'TestPackage'.
Try Get-PSRepository to see all available registered script 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

# The previous command failed because -AllowPrerelease was not specified.
# Adding -AllowPrerelease will result in success.

C:\windows\system32> Install-Script TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease
C:\windows\system32> Get-InstalledScript TestPackage

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

# Note that Get-InstalledScript shows the prerelease version.
# If -RequiredVersion is not specified, all installed scripts will be displayed by Get-InstalledScript

Uninstall-Script quita la versión actual de un script si no se proporciona -RequiredVersion.Uninstall-Script will remove the current version of a script when -RequiredVersion is not supplied. Si se especifica -RequiredVersion y es una versión preliminar, debe agregarse -AllowPrerelease al comando.If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command.

C:\windows\system32> Get-InstalledScript TestPackage

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

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


C:\windows\system32> Uninstall-Script TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease
# Since script versions are not installed side-by-side, the above could be simply "Uninstall-Script TestPackage"

C:\windows\system32> Get-Installedscript TestPackage
PackageManagement\Get-Package : No match was found for the specified search criteria and script names 'testpackage'.
At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.5.0.0\PSModule.psm1:4088 char:9
+         PackageManagement\Get-Package @PSBoundParameters | Microsoft. ...
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Microsoft.Power...lets.GetPackage:GetPackage) [Get-Package], Exception
    + FullyQualifiedErrorId : NoMatchFound,Microsoft.PowerShell.PackageManagement.Cmdlets.GetPackage

Más detallesMore details