Wersje wstępne modułuPrerelease Module Versions

Począwszy od wersji 1.6.0 modułu PowerShellGet oraz spełnione galerii programu PowerShell zapewniają obsługę tagowania w wersjach nowszych niż 1.0.0 jako wersji wstępnej.Starting with version 1.6.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Przed tą funkcją pakiety w wersjach wstępnych były korzystać z wersji począwszy od 0.Prior to this feature, prerelease packages were limited to having a version beginning with 0. Celem tych funkcji jest zapewniają lepsze wsparcie 1.0.0 SemVer Konwencji wersji bez przerywania wstecznej zgodności przy użyciu programu PowerShell 3 i powyżej lub istniejącej wersji programu 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. Ten temat koncentruje się na funkcji specyficznych dla modułu.This topic focuses on the module-specific features. Równoważne funkcje dla skryptów znajdują się w wersję wstępną wersji skryptów tematu.The equivalent features for scripts are in the Prerelease Versions of Scripts topic. Korzystania z tych funkcji, wydawców można zidentyfikować modułu lub skryptu jako 2.5.0-alpha wersji i później wydanej wersji gotowe do produkcji 2.5.0, która zastępuje wersję wstępną.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.

Na wysokim poziomie funkcje wersji wstępnej modułu obejmują:At a high level, the prerelease module features include:

  • Dodawanie ciąg wersji wstępnej do sekcji PSData manifestu modułu identyfikuje moduł jako wersji wstępnej.Adding a Prerelease string to the PSData section of the module manifest identifies the module as a prerelease version. Gdy moduł zostanie opublikowany w galerii programu PowerShell, te dane są wyodrębniane z manifestu i używany do identyfikowania pakiety w wersjach wstępnych.When the module is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease packages.
  • Pobieranie pakietów wydań wstępnych wymaga dodania -AllowPrerelease Flaga poleceń modułu PowerShellGet Find-Module, Install-Module, Update-Module, i Save-Module.Acquiring prerelease packages requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Module, Install-Module, Update-Module, and Save-Module. Jeśli nie określono flagę, pakiety w wersjach wstępnych nie będą wyświetlane.If the flag is not specified, prerelease packages will not be shown.
  • Wersje modułu wyświetlane przez Find-Module, Get-InstalledModule, a w galerii programu PowerShell będą wyświetlane jako pojedynczy ciąg parametrami wstępnej dołączane, tak jak 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.

Poniżej znajdują się szczegółowe informacje dla funkcji.Details for the features are included below.

Te zmiany nie wpływają na obsługę wersji modułu, która jest wbudowana w programie PowerShell i są zgodne z programem PowerShell 3.0 i 4.0, 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.

Identyfikuje wersję modułu jako wersji wstępnejIdentifying a module version as a prerelease

Moduł PowerShellGet obsługę wersji wstępnej wymaga użycia dwóch pól w manifeście modułu:PowerShellGet support for prerelease versions requires the use of two fields within the Module Manifest:

  • ModuleVersion zawarte w manifeście modułu musi być w wersji 3 części, jeśli to wersja wstępna produktu jest używana i musi być zgodne z istniejącej wersji programu PowerShell.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. Format wersji byłoby A.B.C, gdzie A, B i C, to wszystkie liczby całkowite.The version format would be A.B.C, where A, B, and C are all integers.
  • Wstępna ciągu jest określona w manifeście modułu, w sekcji PSData PrivateData.The Prerelease string is specified in the module manifest, in the PSData section of PrivateData.

Szczegółowe wymagania wstępne ciągu są wyświetlane poniżej.Detailed requirements on the Prerelease string are below.

Przykład części manifestu modułu, który definiuje moduł jako wersji wstępnej powinien wyglądać następująco: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'
        }
    }
}

Szczegółowe wymagania wstępne ciągu są następujące:The detailed requirements for Prerelease string are:

  • Ciąg wersji wstępnej może być określona tylko po ModuleVersion 3 segmenty dla główna.pomocnicza.kompilacja.Prerelease string may only be specified when the ModuleVersion is 3 segments for Major.Minor.Build. Jest to zgodne z SemVer 1.0.0.This aligns with SemVer v1.0.0.
  • Łącznik jest separator numer kompilacji i wersji wstępnej ciągu.A hyphen is the delimiter between the Build number and the Prerelease string. Łącznik mogą zostać zawarte w wersji wstępnej ciągu jako pierwszego znaku, tylko.A hyphen may be included in the Prerelease string as the first character, only.
  • Wstępna ciągu może zawierać tylko znaki alfanumeryczne ASCII [0-9A-Za - z-].The Prerelease string may contain only ASCII alphanumerics [0-9A-Za-z-]. Jest najlepszym rozwiązaniem, aby rozpocząć wstępną ciągu za pomocą znaków alfanumerycznych, ponieważ będzie on łatwiej można zidentyfikować, że jest to wersja wstępna produktu podczas skanowania do listy pakietów.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.
  • Tylko SemVer 1.0.0 wstępnej ciągi są obsługiwane w tej chwili.Only SemVer v1.0.0 prerelease strings are supported at this time. Ciąg wersji wstępnej nie zawierać albo okres lub + [. +], mogą SemVer w wersji 2.0.Prerelease string must not contain either period or + [.+], which are allowed in SemVer 2.0.
  • Przykłady obsługiwany ciąg wersji wstępnej:-alfa, - 1,-BETA, - update20171020Examples of supported Prerelease string are: -alpha, -alpha1, -BETA, -update20171020

Wpływ wersji wstępnej w folderach instalacji i kolejność sortowaniaPrerelease versioning impact on sort order and installation folders

Kolejność sortowania zmienia się podczas korzystania z wersji wstępnej, co jest ważne w przypadku publikowania w galerii programu PowerShell, a podczas instalowania modułów przy użyciu poleceń modułu 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. Jeśli ciąg wersji wstępnej jest określona dla dwóch modułów, kolejność sortowania jest oparty na fragment ciągu, postępując łącznika.If the Prerelease string is specified for two modules, the sort order is based on the string portion following the hyphen. Dlatego 2.5.0-alpha wersji jest mniejszy niż 2.5.0-beta, która jest mniejsza niż 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. Jeśli dwa moduły mają ten sam ModuleVersion i tylko jeden ma ciąg wersji wstępnej, modułu bez wstępnej ciągu zakłada, że wersja gotowe do produkcji i będą sortowane jako nowszej wersji niż wersja wstępna, (co obejmuje wersja wstępna ciąg).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). Na przykład podczas porównywania zwalnia 2.5.0 i 2.5.0-beta, 2.5.0 wersji będą uznawane za większa niż dwa.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.

Publikowanie w galerii programu PowerShell, domyślnie wersję modułu publikacji musi mieć nieco większa niż wersja wszystkie wcześniej publikowane w galerii programu PowerShell.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.

Znajdowanie i Uzyskiwanie pakietów wydań wstępnych przy użyciu poleceń modułu PowerShellGetFinding and acquiring prerelease packages using PowerShellGet commands

Obsługa pakietów wydań wstępnych, za pomocą aktualizacji modułu PowerShellGet Find-Module Install-Module-Module, i polecenia Save-Module wymaga dodanie flagi - AllowPrerelease.Dealing with prerelease packages using PowerShellGet Find-Module, Install-Module, Update-Module, and Save-Module commands requires adding the -AllowPrerelease flag. Jeśli określono - AllowPrerelease, pakiety w wersjach wstępnych zostaną dołączone, jeśli są obecne.If -AllowPrerelease is specified, prerelease packages will be included if they are present. Jeśli nie określono flagę - AllowPrerelease, pakiety w wersjach wstępnych nie będą wyświetlane.If -AllowPrerelease flag is not specified, prerelease packages will not be shown.

Jedynym wyjątkiem od tej poleceń modułu PowerShellGet są Get InstalledModule i czasami z modułem dezinstalacji.The only exceptions to this in the PowerShellGet module commands are Get-InstalledModule, and some cases with Uninstall-Module.

  • Get-InstalledModule zawsze automatycznie wyświetli informacje wstępne w ciągu wersji dla modułów.Get-InstalledModule always will automatically show the prerelease information in the version string for modules.
  • Odinstalowanie modułu domyślnie odinstaluje najbardziej aktualną wersję modułu, jeśli nie została zainstalowana wersja jest określony.Uninstall-Module will by default uninstall the most recent version of a module, if no version is specified. To zachowanie nie zmienił się.That behavior has not changed. Jednak jeśli jest to wersja wstępna produktu jest określony, przy użyciu - RequiredVersion, - AllowPrerelease jest wymagana.However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required.

PrzykładyExamples

Załóżmy, że galerii programu PowerShell ma wersje modułu TestPackage 1.8.0 i 1.9.0-alpha.Assume the PowerShell Gallery has TestPackage module versions 1.8.0 and 1.9.0-alpha. Jeśli -AllowPrerelease jest nie określono wersji 1.8.0 zostaną zwrócone.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...

Aby zainstalować wersji wstępnej, należy zawsze określić - AllowPrerelease.To install a prerelease, always specify -AllowPrerelease. Określanie wersji wstępnej ciąg nie jest wystarczające.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

Poprzednie polecenie nie powiodło się, ponieważ nie określono - AllowPrerelease.The previous command failed because -AllowPrerelease was not specified. Dodawanie -AllowPrerelease spowoduje Powodzenie.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...

Instalacja obok siebie wersji modułu, które różnią się tylko ze względu na wersję wstępną określony nie jest obsługiwana.Side-by-side installation of versions of a module that differ only due to the prerelease specified is not supported. Podczas instalowania modułu przy użyciu funkcji PowerShellGet, różne wersje tego samego modułu są zainstalowane side-by-side, tworząc nazwę folderu, za pomocą 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. ModuleVersion, bez wstępnej ciąg jest używany dla nazwy folderu.The ModuleVersion, without the prerelease string, is used for the folder name. Jeśli użytkownik zainstaluje 2.5.0-alpha wersji MyModule, zostanie zainstalowana do MyModule\2.5.0 folderu.If a user installs MyModule version 2.5.0-alpha, it will be installed to the MyModule\2.5.0 folder. Jeśli użytkownik instaluje następnie 2.5.0-beta, wersja 2.5.0-beta będzie zastąpić zawartość folderu 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. Jedną z zalet tego podejścia jest nie musisz odinstalować wstępną wersję po zainstalowaniu wersji gotowe do produkcji.One advantage to this approach is that there is no need to un-install the prerelease version after installing the production-ready version. W poniższym przykładzie pokazano, czego można oczekiwać: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...

Odinstalowanie modułu spowoduje usunięcie najnowszą wersję modułu, jeśli nie podano - RequiredVersion.Uninstall-Module will remove the latest version of a module when -RequiredVersion is not supplied. Jeśli - RequiredVersion zostanie określona, jest w wersji wstępnej, - AllowPrerelease należy dodać do polecenia.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
+ Unnstall-Module TestPackage -RequiredVersion 1.9.0-beta
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Uninstall-Module], ArgumentException
    + FullyQualifiedErrorId : AllowPrereleaseRequiredToUsePrereleaseStringInVersion,Uninnstall-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...

Więcej szczegółówMore details