diff --git a/gallery/psget/module/PreReleaseModule.md b/gallery/psget/module/PreReleaseModule.md new file mode 100644 index 00000000000..2cab01caac9 --- /dev/null +++ b/gallery/psget/module/PreReleaseModule.md @@ -0,0 +1,200 @@ +--- +ms.date: 2017-09-26 +contributor: keithb +ms.topic: reference +keywords: gallery,powershell,cmdlet,psget +title: PrereleaseModule +--- + +# Prerelease Module Versions +Starting with version 1.5.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Prior to this feature, prerelease items were limited to having a version beginning with 0. The goal of these features is to provide greater support for [SemVer v1.0.0](http://semver.org/spec/v1.0.0.html) versioning convention without breaking backwards compatibility with PowerShell versions 3 and above, or existing versions of PowerShellGet. This topic focuses on the module-specific features. The equivalent features for scripts are in the [Prerelease Versions of Scripts](../script/PrereleaseScript.md) topic. 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. + +At a high level, the prerelease module features include: + +* Adding a Prerelease string to the PSData section of the module manifest identifies the module as a prerelease version. +When the module is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease items. +* Acquiring prerelease items requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Module, Install-Module, Update-Module, and Save-Module. +If the flag is not specified, prerelease items will not be shown. +* 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. + +Details for the features are included below. + +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. + +## Identifying a module version as a prerelease + +PowerShellGet support for prerelease versions requires the use of two fields within the Module Manifest: + +* 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. The version format would be A.B.C, where A, B, and C are all integers. +* The Prerelease string is specified in the module manifest, in the PSData section of PrivateData. +Detailed requirements on the Prerelease string are below. + +An example section of a module manifest that defines a module as a prerelease would look like the following: +```powershell +@{ + ModuleVersion = '2.5.0' + #--- + PrivateData = @{ + PSData = @{ + Prerelease = 'alpha' + } + } +} +``` + +The detailed requirements for Prerelease string are: + +* Prerelease string may only be specified when the ModuleVersion is 3 segments for Major.Minor.Build. This aligns with SemVer v1.0.0. +* A hyphen is the delimiter between the Build number and the Prerelease string. A hyphen may be included in the Prerelease string as the first character, only. +* The Prerelease string may contain only ASCII alphanumerics [0-9A-Za-z-]. 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 items. +* Only SemVer v1.0.0 prerelease strings are supported at this time. Prerelease string __must not__ contain either period or + [.+], which are allowed in SemVer 2.0. +* Examples of supported Prerelease string are: -alpha, -alpha1, -BETA, -update20171020 + +__Prerelease versioning impact on sort order and installation folders__ + +Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing modules using PowerShellGet commands. +If the Prerelease string is specified for two modules, the sort order is based on the string portion following the hyphen. So, version 2.5.0-alpha is less than 2.5.0-beta, which is less than 2.5.0-gamma. +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). +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. + +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. + +## Finding and acquiring prerelease items using PowerShellGet commands + +Dealing with prerelease items using PowerShellGet Find-Module, Install-Module, Update-Module, and Save-Module commands requires adding the -AllowPrerelease flag. +If -AllowPrerelease is specified, prerelease items will be included if they are present. +If -AllowPrerelease flag is not specified, prerelease items will not be shown. + +The only exceptions to this in the PowerShellGet module commands are Get-InstalledModule, and some cases with Uninstall-Module. + +* Get-InstalledModule always will automatically show the prerelease information in the version string for modules. +* Uninstall-Module will by default uninstall the most recent version of a module, if __no version__ is specified. That behavior has not changed. However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required. + +## Examples +```powershell +# Assume the PowerShell Gallery has TestPackage module 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-module TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe... + +C:\windows\system32> find-module TestPackage -AllowPrerelease + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe... + +# To install a prerelease, always specify -AllowPrerelease. Specifying a prerelease version string is not sufficient. + +C:\windows\system32> 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], Exceptio + n + + 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-module TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease +C:\windows\system32> Get-InstalledModule TestPackage + +Version Name Repository Description +------- ---- ---------- ----------- +1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe... + +``` + +Side-by-side installation of versions of a module that differ only due to the prerelease specified is not supported. +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. +The ModuleVersion, without the prerelease string, is used for the folder name. +If a user installs MyModule version 2.5.0-alpha, it will be installed to the MyModule\2.5.0 folder. +If the user then installs 2.5.0-beta, the 2.5.0-beta version will __over-write__ the contents of the folder MyModule\2.5.0. +One advantage to this approach is that there is no need to un-install the prerelease version after installing the production-ready version. +The example below shows what to expect: + + +``` powershell +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 will remove the latest version of a module when -RequiredVersion is not supplied. +If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command. + +``` powershell +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... + + +``` + + + +## More details +### [Prerelease Script Versions](../script/PrereleaseScript.md) +### [Find-Module](./psget_find-module.md) +### [Install-Module](./psget_install-module.md) +### [Save-Module](./psget_save-module.md) +### [Update-Module](./psget_update-module.md) +### [Get-InstalledModule](./psget_get-installedmodule.md) +### [UnInstall-Module](./psget_uninstall-module.md) diff --git a/gallery/psget/module/psget_find-module.md b/gallery/psget/module/psget_find-module.md index 4149e0c1ec5..3e940ab6a23 100644 --- a/gallery/psget/module/psget_find-module.md +++ b/gallery/psget/module/psget_find-module.md @@ -63,6 +63,9 @@ Find-Module -Name PSReadline -MinimumVersion 1.0.0.12 -MaximumVersion 1.0.0.13 # Find a module with exact version Find-Module -Name AzureRM -RequiredVersion 1.3.2 +# Find a module with a specific prerelease version +Find-Module -Name AzureRM -RequiredVersion 1.3.2-alpha -AllowPrerelease + # Find a module from the specified repository Find-Module -Name Contoso -Repository MyLocalRepo diff --git a/gallery/psget/module/psget_install-module.md b/gallery/psget/module/psget_install-module.md index 75024aea774..fd159d37f60 100644 --- a/gallery/psget/module/psget_install-module.md +++ b/gallery/psget/module/psget_install-module.md @@ -77,6 +77,12 @@ Install-Module -Name ContosoServer -MinimumVersion 1.0 # Install a specific version of a module Install-Module -Name ContosoServer -RequiredVersion 1.1.3 +# Install a specific prerelease version of a module +Install-Module -Name ContosoServer -RequiredVersion 1.1.3-alpha -AllowPrerelease + +# Install the latest version of a module by name, including prelrelease versions if one exists +Install-Module -Name ContosoServer -AllowPrerelease + # Install the latest version of a module to $home\Documents\WindowsPowerShell\Modules. Install-Module -Name ContosoServer -Scope CurrentUser diff --git a/gallery/psget/module/psget_save-module.md b/gallery/psget/module/psget_save-module.md index fbc1a66d995..56a980cb978 100644 --- a/gallery/psget/module/psget_save-module.md +++ b/gallery/psget/module/psget_save-module.md @@ -50,5 +50,14 @@ Find-Command -Name "Get-NestedRequiredModule4" -Repository "INT" | Save-Module - # Save the role capability modules by piping the Find-RoleCapability output to Save-Module cmdlet. Find-RoleCapability -Name Maintenance,MyJeaRole | Save-Module -Path C:\MyModulesPath + +# Save a specific prerelease version of a module to C:\MySavedModuleLocation +Save-Module -Name ContosoServer -RequiredVersion 1.1.3-alpha -Path C:\MySavedModuleLocation -AllowPrerelease + +# Install the latest version of a module by name, including prelrelease versions if one exists +Install-Module -Name ContosoServer -Path C:\MySavedModuleLocation -AllowPrerelease + + + ``` diff --git a/gallery/psget/module/psget_update-module.md b/gallery/psget/module/psget_update-module.md index 940fc06ee9f..7e5fb685b7d 100644 --- a/gallery/psget/module/psget_update-module.md +++ b/gallery/psget/module/psget_update-module.md @@ -39,38 +39,38 @@ Get-Command -Name Update-Module -Module PowerShellGet -Syntax ## Example commands ```powershell -PS C:\\windows\\system32> Update-Module -Name ContosoServer -RequiredVersion 1.5 -PS C:\\windows\\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase +PS C:\windows\system32> Update-Module -Name ContosoServer -RequiredVersion 1.5 +PS C:\windows\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase Name : ContosoServer Version : 2.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.0 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.0 Name : ContosoServer Version : 1.5 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.5 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.5 Name : ContosoServer Version : 1.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.0 -PS C:\\windows\\system32> Get-InstalledModule +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.0 +PS C:\windows\system32> Get-InstalledModule Version Name Repository Description ------- ---- ---------- ----------- 1.0 ContosoServer MSPSGallery ContosoServer module 1.5 ContosoServer MSPSGallery ContosoServer module 2.0 ContosoServer MSPSGallery ContosoServer module -PS C:\\windows\\system32> Update-Module -Name ContosoServer -PS C:\\windows\\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase +PS C:\windows\system32> Update-Module -Name ContosoServer +PS C:\windows\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase Name : ContosoServer Version : 2.8.1 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.8.1 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.8.1 Name : ContosoServer Version : 2.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.0 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.0 Name : ContosoServer Version : 1.5 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.5 +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.5 Name : ContosoServer Version : 1.0 -ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.0 -PS C:\\windows\\system32> Get-InstalledModule +ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.0 +PS C:\windows\system32> Get-InstalledModule Version Name Repository Description ------- ---- ---------- ----------- 1.0 ContosoServer MSPSGallery ContosoServer module @@ -79,8 +79,36 @@ Version Name Repository Description 2.8.1 ContosoServer MSPSGallery ContosoServer module ``` +### Update the module with a prerelease version, requires -AllowPrerelease flag +```powershell +PS C:\windows\system32> Get-InstalledModule +Version Name Repository Description +------- ---- ---------- ----------- +1.0 ContosoServer MSPSGallery ContosoServer module +1.5 ContosoServer MSPSGallery ContosoServer module +2.0 ContosoServer MSPSGallery ContosoServer module +2.8.1 ContosoServer MSPSGallery ContosoServer module + +PS C:\windows\system32> Find-Module ContosoServer -AllowPrerelease + +Version Name Repository Description +------- ---- ---------- ----------- +3.0.0-alpha ConstosoServer MSPSGallery The PowerShell Contoso Server deployment tools... + +PS C:\windows\system32> Update-Module -Name ContosoServer -AllowPrerelease +PS C:\windows\system32> Get-InstalledModule +Version Name Repository Description +------- ---- ---------- ----------- +1.0 ContosoServer MSPSGallery ContosoServer module +1.5 ContosoServer MSPSGallery ContosoServer module +2.0 ContosoServer MSPSGallery ContosoServer module +2.8.1 ContosoServer MSPSGallery ContosoServer module +3.0.0-alpha ContosoServer MSPSGallery ContosoServer module -### Update the TestDepWithNestedRequiredModules1 module with dependencies. +``` + + +### Update the TestDepWithNestedRequiredModules1 module with dependencies. ```powershell Find-Module -Name TestDepWithNestedRequiredModules1 -Repository LocalRepo -AllVersions @@ -104,5 +132,8 @@ Version    Name                                2.5        RequiredModule3                     LocalRepo   RequiredModule3 module 1.0        TestDepWithNestedRequiredModules1   LocalRepo   TestDepWithNestedRequiredModules1 module 2.0        TestDepWithNestedRequiredModules1   LocalRepo   TestDepWithNestedRequiredModules1 module + + + ``` diff --git a/gallery/psget/script/PreReleaseScript.md b/gallery/psget/script/PreReleaseScript.md new file mode 100644 index 00000000000..6994325405d --- /dev/null +++ b/gallery/psget/script/PreReleaseScript.md @@ -0,0 +1,157 @@ +--- +ms.date: 2017-10-17 +contributor: keithb +ms.topic: reference +keywords: gallery,powershell,cmdlet,psget +title: PrereleaseScript +--- + +# Prerelease Versions of Scripts + +Starting with version 1.5.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Prior to this feature, prerelease items were limited to having a version beginning with 0. The goal of these features is to provide greater support for [SemVer v1.0.0](http://semver.org/spec/v1.0.0.html) versioning convention without breaking backwards compatibility with PowerShell versions 3 and above, or existing versions of PowerShellGet. +This topic focuses on the script-specific features. The equivalent features for modules are in the [Prerelease Module Versions](../module/PrereleaseModule.md) topic. 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. + +At a high level, the prerelease script features include: + +* Adding a PrereleaseString suffix to the version string in the script manifest. +When the scripts is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease items. +* Acquiring prerelease items requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Script, Install-Script, Update-Script, and Save-Script. +If the flag is not specified, prerelease items will not be shown. +* 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. + +Details for the features are included below. + + +## Identifying a script version as a prerelease + +PowerShellGet support for prerelease versions is easier for scripts than modules. +Script versioning is only supported by PowerShellGet, so there are no compatibility issues caused by adding the prerelease string. +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. + +An example section of a script manifest with a prerelease version would look like the following: +```powershell +<#PSScriptInfo + +.VERSION 3.2.1-alpha12 + +.GUID + +... + +#> + +``` + +To use a prerelease suffix, the version string must meet the following requirements: + +* A prerelease suffix may only be specified when the Version is 3 segments for Major.Minor.Build. This aligns with SemVer v1.0.0 +* The prerelease suffix is a string which begins with a hyphen, and may contain ASCII alphanumerics [0-9A-Za-z-] +* 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 +* Examples of supported PrereleaseString strings are: -alpha, -alpha1, -BETA, -update20171020 + +__Prerelease versioning impact on sort order and installation folders__ + +Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing scripts using PowerShellGet commands. +If two scripts versions with the version number exist, the sort order is based on the string portion following the hyphen. So, version 2.5.0-alpha is less than 2.5.0-beta, which is less than 2.5.0-gamma. +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. +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. + +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. +A publisher may update version 2.5.0-alpha with 2.5.0-beta, or with 2.5.0 (with no prerelease suffix). + +## Finding and acquiring prerelease items using PowerShellGet commands + +Dealing with prerelease items using PowerShellGet Find-Script, Install-Script, Update-Script, and Save-Script commands requires adding the -AllowPrerelease flag. +If -AllowPrerelease is specified, prerelease items will be included if they are present. +If -AllowPrerelease flag is not specified, prerelease items will not be shown. + +The only exceptions to this in the PowerShellGet script commands are Get-InstalledScript, and some cases with Uninstall-Script. + +* Get-InstalledScript always will automatically show the prerelease information in the version string if it is present. +* Uninstall-Script will by default uninstall the most recent version of a script, if __no version__ is specified. That behavior has not changed. However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required. + +## Examples +```powershell +# 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], Exceptio + n + + 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 will remove the current version of a script when -RequiredVersion is not supplied. +If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command. + +``` powershell +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 ++ Unnstall-Script TestPackage -RequiredVersion 1.9.0-beta ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Uninstall-Script], ArgumentException + + FullyQualifiedErrorId : AllowPrereleaseRequiredToUsePrereleaseStringInVersion,Uninnstall-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 + + +``` + + + +## More details +### [Prerelease Module Versions](../module/PrereleaseModule.md) +### [Find-script](./psget_find-script.md) +### [Install-script](./psget_install-script.md) +### [Save-script](./psget_save-script.md) +### [Update-script](./psget_update-script.md) +### [Get-Installedscript](./psget_get-installedscript.md) +### [UnInstall-script](./psget_uninstall-script.md) diff --git a/gallery/psget/script/psget_find-script.md b/gallery/psget/script/psget_find-script.md index a44466e472d..ffb040210df 100644 --- a/gallery/psget/script/psget_find-script.md +++ b/gallery/psget/script/psget_find-script.md @@ -70,6 +70,9 @@ Find-Script -Name Connect-O365 -MinimumVersion 1.1 -MaximumVersion 1.6.2 # Find a script with exact version Find-Script -Name Connect-O365 -RequiredVersion 1.5.7 +# Find a script with a specific pre-release version +Find-Script -Name Connect-O365 -RequiredVersion 1.3.2-alpha -AllowPrerelease + # Find a script from the specified repository Find-Script -Name Fabrikam-ServerScript -Repository MyLocalRepo diff --git a/gallery/psget/script/psget_install-script.md b/gallery/psget/script/psget_install-script.md index 8f1c5e26ce6..89f0a11e1f1 100644 --- a/gallery/psget/script/psget_install-script.md +++ b/gallery/psget/script/psget_install-script.md @@ -10,38 +10,30 @@ title: Install-Script Installs the PowerShell script files from online repositories to the local computer. - ## Description -The Install-Script cmdlet acquires a script payload from a repository, verifies that the payload is a valid PowerShell script, and copies the script file to a specified installation location. - -The default repositories Install-Script operates against are configurable through the Register-PSRepository, Set-PSRepository, Unregister-PSRepository, and Get-PSRepository cmdlets. When operating against multiple repositories, Install-Script installs the first script that matches the specified search criteria (Name, MinimumVersion, or MaximumVersion) from the first repository without any error. - - -Install-Script cmdlet downloads one or more modules from an online gallery, validates and installs them on the local computer to the specified installation scope. +The Install-Script cmdlet finds and downloads one or more scripts from an online gallery, validates and installs them on the local computer to the specified installation scope. -The Install-Script cmdlet gets one or more modules that meet specified criteria from an online gallery, verifies that search results are valid modules, and copies module folders to the installation location. +When no scope is defined, or when the value of the Scope parameter is AllUsers, the script is installed to %systemdrive%:\Program Files\WindowsPowerShell\scripts. When the value of Scope is CurrentUser, the script is installed to $home\Documents\WindowsPowerShell\scripts. -When no scope is defined, or when the value of the Scope parameter is AllUsers, the module is installed to %systemdrive%:\Program Files\WindowsPowerShell\Modules. When the value of Scope is CurrentUser, the module is installed to $home\Documents\WindowsPowerShell\Modules. +You can filter your results based on minimum and exact versions of specified scripts. -You can filter your results based on minimum and exact versions of specified modules. - -- No Side-by-side version support for PowerShell Script files -- Script dependency installation support -- **Untrusted prompt:** User acceptance is required for installing the modules from an untrusted repository. -- -Force reinstalls the installed module +Some important notes: +- Scripts are installed single files. As a result, only one copy of a script is installed, and multiple versions of scripts cannot be installed side-by-side on a system. +- Scripts may define dependencies on external modules, which will be installed when Install-Script is run. +- **Untrusted prompt:** User acceptance is required for installing the scripts from an untrusted repository. - RequiredVersion installs the specified version in SxS with existing versions on PowerShell version 5.0 or newer. -Wildcards are not supported in -Name on Install-Module, Save-Module, Uninstall-Module, Install-Script, Save-Script, and Uninstall-Script cmdlets. +Wildcards are not supported in -Name on Install-Script, Save-Script, and Uninstall-Script cmdlets. ### Scope -Specifies the installation scope of the module. The acceptable values for this parameter are: AllUsers and CurrentUser. +Specifies the installation scope of the script. The acceptable values for this parameter are: AllUsers and CurrentUser. The default installation scope is AllUsers. -The AllUsers scope lets modules be installed in a location that is accessible to all users of the computer, that is, "$env:SystemDrive\Program Files\WindowsPowerShell\Modules". +The AllUsers scope lets scripts be installed in a location that is accessible to all users of the computer, that is, "$env:SystemDrive\Program Files\WindowsPowerShell\scripts". -The CurrentUser scope lets modules be installed only to "$home\Documents\WindowsPowerShell\Modules", so that the module is available only to the current user. +The CurrentUser scope lets scripts be installed only to "$home\Documents\WindowsPowerShell\scripts", so that the script is available only to the current user. Specifies the installation scope of the script. Valid values are: AllUsers and CurrentUser. The default is CurrentUser. @@ -62,17 +54,15 @@ The AllUsers scope specifies to install a script to %systemdrive%:\ProgramFiles\ This cmdlet runs on Windows PowerShell 3.0 or later releases of Windows PowerShell, on Windows 7 or Windows 2008 R2 and later releases of Windows. -If an installed module cannot be imported (that is, if it does not have a .psm1, .psd1, or .dll of the same name within the folder), installation fails unless you add the Force parameter to your command. - -If a version of the module on the computer matches the value specified for the Name parameter, and you have not added the MinimumVersion or RequiredVersion parameter, Install-Script silently continues without installing that module. If the MinimumVersion or RequiredVersion parameters are specified, and the existing module does not match the values in that parameter, then an error occurs. To be more specific: if the version of the currently-installed module is either lower than the value of the MinimumVersion parameter, or not equal to the value of the RequiredVersion parameter, an error occurs. If the version of the installed module is greater than the value of the MinimumVersion parameter, or equal to the value of the RequiredVersion parameter, Install-Script silently continues without installing that module. +If a version of the script on the computer matches the value specified for the Name parameter, and you have not added the MinimumVersion or RequiredVersion parameter, Install-Script silently continues without installing that script. If the MinimumVersion or RequiredVersion parameters are specified, and the existing script does not match the values in that parameter, then an error occurs. To be more specific: if the version of the currently-installed script is either lower than the value of the MinimumVersion parameter, or not equal to the value of the RequiredVersion parameter, an error occurs. If the version of the installed script is greater than the value of the MinimumVersion parameter, or equal to the value of the RequiredVersion parameter, Install-Script silently continues without installing that script. -Install-Script returns an error if no module exists in the online gallery that matches the specified name. +Install-Script returns an error if no script exists in the online gallery that matches the specified name. -To install multiple modules, specify an array of the module names, separated by commas. You cannot add MinimumVersion or RequiredVersion if you specify multiple module names. +To install multiple scripts, specify an array of the script names, separated by commas. You cannot add MinimumVersion or RequiredVersion if you specify multiple script names. -By default, modules are installed to the Program Files folder, to prevent confusion when you are installing Windows PowerShell Desired State Configuration (DSC) resources.You can pipe multiple PSGetItemInfo objects to Install-Script; this is another way of specifying multiple modules to install in a single command. +By default, scripts are installed to the Program Files folder. You can pipe multiple PSGetItemInfo objects to Install-Script; this is another way of specifying multiple scripts to install in a single command. -To help prevent running modules that contain malicious code, installed modules are not automatically imported by installation. As a security best practice, evaluate module code before running any cmdlets or functions in a module for the first time. +To help prevent running scripts that contain malicious code, installed scripts are not automatically imported by installation. As a security best practice, evaluate script code before running any cmdlets or functions in a script for the first time. ## Cmdlet syntax @@ -293,42 +283,46 @@ ExternalScript Required-Script2.ps1 C:\\Users\\manikb\\Documents\\WindowsPowerSh ```powershell -# Install a module by name -Install-Script -Name MyDscModule +# Install a script by name +Install-Script -Name MyDscscript -# Install multiple modules +# Install multiple scripts Install-Script ContosoClient,ContosoServer -# Install a module using its minimum version +# Install a script using its minimum version Install-Script -Name ContosoServer -MinimumVersion 1.0 -# Install a specific version of a module +# Install a specific version of a script Install-Script -Name ContosoServer -RequiredVersion 1.1.3 -# Install the latest version of a module to $home\Documents\WindowsPowerShell\Modules. +# Install a specific prerelease version of a script +Install-Script -Name ContosoServer -RequiredVersion 1.1.3-alpha -AllowPrerelease + +# Install the latest version of a script to $home\Documents\WindowsPowerShell\scripts. Install-Script -Name ContosoServer -Scope CurrentUser -# if a module is already available under $env:PSModulePath, below command fails with 'ModuleAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' +# if a script is already available under $env:PSModulePath, below command fails with 'scriptAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' Install-Script ContosoServer -RequiredVersion 1.5 -# if a module is already available under $env:PSModulePath, below command fails with 'ModuleAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' +# if a script is already available under $env:PSModulePath, below command fails with 'scriptAlreadyInstalled,Install-Package,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage' Install-Script ContosoServer -MinimumVersion 2.5 -# Install multiple modules from multiple registered repositories +# Install multiple scripts from multiple registered repositories Install-Script ContosoClient,ContosoServer -Repository PSGallery, PrivatePSGallery -# Install a module with -WhatIf +# Install a script with -WhatIf Install-Script ContosoClient -WhatIf -# Install a module with -Confirm. A prompt will be displayed to confirm the installation. +# Install a script with -Confirm. A prompt will be displayed to confirm the installation. Install-Script ContosoClient -WhatIf -# -Force option reinstalls the installed module +# -Force option reinstalls the installed script Install-Script ContosoClient -Force -# Install a module with dependencies -Install-Script -Name +# Install a script with dependencies +Install-Script -Name ContosoClient +# Install a script # Install a script from the registered repository with ScriptSourceLocation Install-Script Connect-AzureVM @@ -471,158 +465,25 @@ The scripts install location 'C:\Program Files\WindowsPowerShell\Scripts' is req ```powershell -# Find a module and install it +# Find a script and install it Find-Script -Name "MyDSC*" | Install-Script -# Find a module and install it to the CurrentUser scope +# Find a script and install it to the CurrentUser scope Find-Script -Name "MyDSC*" | Install-Script -Scope CurrentUser # Find commands by name and install them # The first command finds the specified commands in the INT repository, and then uses the pipeline operator to pass them to Install-Script to install them. -# The second command uses Get-InstalledModule to verify the modules from the prior command are installed. +# The second command uses Get-Installedscript to verify the scripts from the prior command are installed. Find-Command -Repository "INT" -Name Get-ContosoClient,Get-ContosoServer | Install-Script -Get-InstalledModule - -# This command finds the resource named MyResource and passes it to the Install-Script cmdlet by using the pipeline operator. The Install-Script cmdlet installs the module for the resource. -# If you pipe multiple resources to the Install-Script cmdlet from the same module, Install-Script attempts to install the module only once. -Find-DscResource -Name "MyResource" | Install-Script -Get-InstalledModule +Get-Installedscript # Find multiple role capabilities and install them Find-RoleCapability -Name MyJeaRole, Maintenance | Install-Script -Get-InstalledModule - -``` - -## Side-by-Side Version Support on PowerShell 5.0 or newer - -PowerShellGet supports the side-by-side (SxS) module version support in Install-Script, Update-Script, and Publish-Script cmdlets that run in Windows PowerShell 5.0 or newer. - -### Install-Script examples - -```powershell -# Install a version of the module -Install-Script -Name PSScriptAnalyzer -RequiredVersion 1.1.0 -Repository PSGallery -Get-Script -ListAvailable -Name PSScriptAnalyzer | Format-List Name,Version,ModuleBase - -Name : PSScriptAnalyzer -Version : 1.1.0 -ModuleBase : C:\Program Files\WindowsPowerShell\Modules\PSScriptAnalyzer\1.1.0 - -# Install another version of the module in Side-by-Side with already installed version. -Install-Script -Name PSScriptAnalyzer -RequiredVersion 1.1.1 -Repository PSGallery -Get-Script -ListAvailable -Name PSScriptAnalyzer | Format-List Name,Version,ModuleBase - -Name : PSScriptAnalyzer -Version : 1.1.1 -ModuleBase : C:\Program Files\WindowsPowerShell\Modules\PSScriptAnalyzer\1.1.1 -Name : PSScriptAnalyzer -Version : 1.1.0 -ModuleBase : C:\Program Files\WindowsPowerShell\Modules\PSScriptAnalyzer\1.1.0 - -# Get all versions of an installed module -Get-InstalledModule -Name PSScriptAnalyzer -AllVersions -Version Name Repository Description -------- ---- ---------- ----------- -1.1.0 PSScriptAnalyzer PSGallery PSScriptAnalyzer provides script analysis... -1.1.1 PSScriptAnalyzer PSGallery PSScriptAnalyzer provides script analysis... - +Get-Installedscript ``` -## Install module with its dependencies - -```powershell - -# Find a module -Find-Module -Name TypePx -Repository PSGallery - -Version Name Repository Description -------- ---- ---------- ----------- -2.0.1.20 TypePx PSGallery The TypePx module adds properties and methods to the m... - -# Find a module and its dependencies -Find-Module -Name TypePx -Repository PSGallery -IncludeDependencies - -Version Name Repository Description -------- ---- ---------- ----------- -2.0.1.20 TypePx PSGallery The TypePx module adds properties and methods to the m... -1.0.5.18 SnippetPx PSGallery The SnippetPx module enhances the snippet experience i... - -# Discover the dependencies list without adding -IncludeDependencies -$result = Find-Module -Name TypePx -Repository PSGallery -$result.Dependencies - -Name Value ----- ----- -Name SnippetPx -CanonicalId powershellget:SnippetPx/#https://www.powershellgallery.com/api/v2/ - - -# Now install the module along with its dependencies -Install-Script -Name TypePx -Repository PSGallery -Verbose - -VERBOSE: Repository details, Name = 'PSGallery', Location = 'https://www.powershellgallery.com/api/v2/'; IsTrusted = -'False'; IsRegistered = 'True'. -VERBOSE: Using the provider 'PowerShellGet' for searching packages. -VERBOSE: Using the specified source names : 'PSGallery'. -VERBOSE: Getting the provider object for the PackageManagement Provider 'NuGet'. -VERBOSE: The specified Location is 'https://www.powershellgallery.com/api/v2/' and PackageManagementProvider is -'NuGet'. -VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id='TypePx'' for ''. -VERBOSE: Total package yield:'1' for the specified package 'TypePx'. -VERBOSE: Performing the operation "Install-Script" on target "Version '2.0.1.20' of module 'TypePx'". - -Untrusted repository -You are installing the modules from an untrusted repository. If you trust this repository, change its -InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from -'PSGallery'? -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): Y -VERBOSE: The installation scope is specified to be 'AllUsers'. -VERBOSE: The specified module will be installed in 'C:\Program Files\WindowsPowerShell\Modules'. -VERBOSE: The specified Location is 'NuGet' and PackageManagementProvider is 'NuGet'. -VERBOSE: Downloading module 'TypePx' with version '2.0.1.20' from the repository -'https://www.powershellgallery.com/api/v2/'. -VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id='TypePx'' for ''. -VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id='SnippetPx'' for ''. -VERBOSE: InstallPackage' - name='SnippetPx', -version='1.0.5.18',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: DownloadPackage' - name='SnippetPx', -version='1.0.5.18',destination='C:\Users\manikb\AppData\Local\Temp\1027042896\SnippetPx\SnippetPx.nupkg', -uri='https://www.powershellgallery.com/api/v2/package/SnippetPx/1.0.5.18' -VERBOSE: Downloading 'https://www.powershellgallery.com/api/v2/package/SnippetPx/1.0.5.18'. -VERBOSE: Completed downloading 'https://www.powershellgallery.com/api/v2/package/SnippetPx/1.0.5.18'. -VERBOSE: Completed downloading 'SnippetPx'. -VERBOSE: Hash for package 'SnippetPx' does not match hash provided from the server. -VERBOSE: InstallPackageLocal' - name='SnippetPx', -version='1.0.5.18',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: InstallPackage' - name='TypePx', -version='2.0.1.20',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: DownloadPackage' - name='TypePx', -version='2.0.1.20',destination='C:\Users\manikb\AppData\Local\Temp\1027042896\TypePx\TypePx.nupkg', -uri='https://www.powershellgallery.com/api/v2/package/TypePx/2.0.1.20' -VERBOSE: Downloading 'https://www.powershellgallery.com/api/v2/package/TypePx/2.0.1.20'. -VERBOSE: Completed downloading 'https://www.powershellgallery.com/api/v2/package/TypePx/2.0.1.20'. -VERBOSE: Completed downloading 'TypePx'. -VERBOSE: Hash for package 'TypePx' does not match hash provided from the server. -VERBOSE: InstallPackageLocal' - name='TypePx', -version='2.0.1.20',destination='C:\Users\manikb\AppData\Local\Temp\1027042896' -VERBOSE: Installing the dependency module 'SnippetPx' with version '1.0.5.18' for the module 'TypePx'. -VERBOSE: Module 'SnippetPx' was installed successfully to path 'C:\Program -Files\WindowsPowerShell\Modules\SnippetPx\1.0.5.18'. -VERBOSE: Module 'TypePx' was installed successfully to path 'C:\Program -Files\WindowsPowerShell\Modules\TypePx\2.0.1.20'. - - -# Get the installed modules -Get-InstalledModule - -Version Name Repository Description -------- ---- ---------- ----------- -1.0.5.18 SnippetPx PSGallery The SnippetPx module enhances the snippet experience i... -2.0.1.20 TypePx PSGallery The TypePx module adds properties and methods to the m... -``` ## Error scenarios @@ -642,79 +503,6 @@ Install-Script ContosoClient,ContosoServer -MinimumVersion 2.0 ``` -## Installing a script with dependent scripts and modules - -```powershell -# Installing a script with dependent scripts and modules -Find-Script -Repository GalleryINT -Name Script-WithDependencies2 -IncludeDependencies -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.0 Script-WithDependencies2 Script GalleryINT Description for the Script-WithDependencies2 script -2.5 RequiredModule1 Module GalleryINT RequiredModule1 module -2.5 RequiredModule2 Module GalleryINT RequiredModule2 module -2.5 RequiredModule3 Module GalleryINT RequiredModule3 module -2.0 RequiredModule4 Module GalleryINT RequiredModule4 module -1.5 RequiredModule5 Module GalleryINT RequiredModule5 module -2.5 Required-Script1 Script GalleryINT Description for the Required-Script1 script -2.5 Required-Script2 Script GalleryINT Description for the Required-Script2 script -2.5 Required-Script3 Script GalleryINT Description for the Required-Script3 script - -Get-InstalledScript -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.0 Required-Script3 Script GalleryINT Description for the Required-Script3 script -1.0 Demo-Script Script LocalRepo1 Script file description goes here -2.5 Required-Script2 Script GalleryINT Description for the Required-Script2 script -Get-InstalledModule -Install-Script -Repository GalleryINT -Name Script-WithDependencies2 -Scope CurrentUser -Get-InstalledScript -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.0 Required-Script3 Script GalleryINT Description for the Required-Script3 script -1.0 Demo-Script Script LocalRepo1 Script file description goes here -2.5 Required-Script1 Script GalleryINT Description for the Required-Script1 script -2.5 Required-Script2 Script GalleryINT Description for the Required-Script2 script -2.0 Script-WithDependencies2 Script GalleryINT Description for the Script-WithDependencies2 script -Get-InstalledModule -Version Name Type Repository Description -------- ---- ---- ---------- ----------- -2.5 RequiredModule1 Module GalleryINT RequiredModule1 module -2.5 RequiredModule2 Module GalleryINT RequiredModule2 module -2.5 RequiredModule3 Module GalleryINT RequiredModule3 module -2.0 RequiredModule4 Module GalleryINT RequiredModule4 module -1.5 RequiredModule5 Module GalleryINT RequiredModule5 module - -# Contents of Script-WithDependencies2 file. -<#PSScriptInfo -.VERSION 2.0 -.GUID 90082fa1-0b84-49fb-a00e-0a624fbb6584 -.AUTHOR manikb -.COMPANYNAME Microsoft Corporation -.COPYRIGHT (c) 2015 Microsoft Corporation. All rights reserved. -.TAGS Tag1 Tag2 Tag-Script-WithDependencies2-2.0 -.LICENSEURI http://script-withdependencies2.com/license -.PROJECTURI http://script-withdependencies2.com/ -.ICONURI http://script-withdependencies2.com/icon -.EXTERNALMODULEDEPENDENCIES -.REQUIREDSCRIPTS Required-Script1,Required-Script2,Required-Script3 -.EXTERNALSCRIPTDEPENDENCIES -.RELEASENOTES -Script-WithDependencies2 release notes -#> -#Requires -Module RequiredModule1 -#Requires -Module @{ModuleName = 'RequiredModule2'; ModuleVersion = '2.0'} -#Requires -Module @{RequiredVersion = '2.5'; ModuleName = 'RequiredModule3'} -#Requires -Module @{ModuleVersion = '1.1'; ModuleName = 'RequiredModule4'; MaximumVersion = '2.0'} -#Requires -Module @{MaximumVersion = '1.5'; ModuleName = 'RequiredModule5'} -<# -.DESCRIPTION -Description for the Script-WithDependencies2 script -#> -Param() -Function Test-FunctionFromScript\_Script-WithDependencies2 { Get-Date } -Workflow Test-WorkflowFromScript\_Script-WithDependencies2 { Get-Date } -``` - ## Install-Script and Get-InstalledScript cmdlets Install-Script cmdlet lets you to install a specific script file along with its dependencies to the specified scope. By default, scripts are installed to the AllUsers scope. Get-InstalledScript cmdlet lets you to get the list of script files which were installed using Install-Script cmdlet. diff --git a/gallery/psget/script/psget_save-script.md b/gallery/psget/script/psget_save-script.md index 6668e1ef1cc..9eae7d135ca 100644 --- a/gallery/psget/script/psget_save-script.md +++ b/gallery/psget/script/psget_save-script.md @@ -1,6 +1,6 @@ --- -ms.date: 2017-06-12 -contributor: manikb +ms.date: 2017-10-17 +contributor: keithb ms.topic: reference keywords: gallery,powershell,cmdlet,psget title: Save-Script @@ -47,3 +47,10 @@ Version Name Author Description 1.5 Fabrikam-ClientScript manikb Description for the Fabrikam-ClientScript script ``` +### Example 3: Save a prerelease version of a script from a repository +This command saves the latest version of the script Fabrikam-ClientScript from GalleryINT repository to the local folder C:\ScriptSharingDemo + +```powershell +Save-Script -Name Fabrikam-ClientScript -Path C:\ScriptSharingDemo -AllowPrerelease +``` + diff --git a/gallery/psget/script/psget_uninstall-script.md b/gallery/psget/script/psget_uninstall-script.md index e130fa7c29f..ef262032985 100644 --- a/gallery/psget/script/psget_uninstall-script.md +++ b/gallery/psget/script/psget_uninstall-script.md @@ -62,5 +62,11 @@ At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : ObjectNotFound: (Microsoft.Power...lets.GetPackage:GetPackage) [Get-Package], Exception + FullyQualifiedErrorId : NoMatchFound,Microsoft.PowerShell.PackageManagement.Cmdlets.GetPackage + +# Uninstall a specified prerelease version of a script +Uninstall-Script Required-Script1 -RequiredVersion 2.5.0-alpha -AllowPrerelease -Verbose +VERBOSE: Performing the operation "Uninstall-Script" on target "Version '2.5.0-alpha' of script 'Required-Script1'". +VERBOSE: Successfully uninstalled the script 'Required-Script1' from script base 'C:\Users\manikb\Documents\WindowsPowerShell\Scripts'. + ``` diff --git a/gallery/psget/script/psget_update-script.md b/gallery/psget/script/psget_update-script.md index 2f91cfe891d..963ac527b9c 100644 --- a/gallery/psget/script/psget_update-script.md +++ b/gallery/psget/script/psget_update-script.md @@ -38,6 +38,13 @@ Version Name Type Repository Description ------- ---- ---- ---------- ----------- 1.5 Fabrikam-Script Script GalleryINT Description for the Fabrikam-Script script +# Update a specific script to the required prerelease version +Update-Script -Name Fabrikam-Script -RequiredVersion 1.5.0-alpha -AllowPrerelease +Get-InstalledScript -Name Fabrikam-Script +Version Name Type Repository Description +------- ---- ---- ---------- ----------- +1.5.0-alpha Fabrikam-Script Script GalleryINT Description for the Fabrikam-Script script + # Update all installed scripts Install-Script -Name Fabrikam-ServerScript -RequiredVersion 1.0 -Repository GalleryINT -Scope CurrentUser Get-InstalledScript