Add support for Uninstall-PSResource (#593)

Add support for Uninstall -Prerelease parameter uninstalling only prerelease versions

Author: anamnavi

help/Get-PSResource.md

@@ -26,7 +26,7 @@ The Get-PSResource cmdlet combines the Get-InstalledModule, Get-InstalledScript
 PS C:\> Get-PSResource Az
 ```
 
-This will return versions of the Az module installed via PowerShellGet.
+This will return versions (stable and prerelease) of the Az module installed via PowerShellGet.
 
 ### Example 2
 ```powershell
@@ -44,12 +44,32 @@ This will return all versions of the Az module within the specified range.
 
 ### Example 4
 ```powershell
+PS C:\> Get-PSResource Az -version "4.0.1-preview"
+```
+
+Assume that the package Az version 4.0.1-preview is already installed. This will return version 4.0.1-preview of the Az module.
+
+```powershell
+PS C:\> Get-PSResource Az -version "4.0.1"
+```
+Assume that the package Az version 4.0.1-preview is already installed. This will not return Az version 4.0.1-preview as the full version (including prerelease label, i.e "4.0.1-preview") was not specified.
+
+### Example 5
+```powershell
+PS C:\> Get-PSResource Az -Version "[4.0.1, 4.0.2-preview]
+```
+
+Assume that the following versions are already installed for package Az: 4.0.1-preview and 4.0.2-preview. This will only return version 4.0.2-preview as it is the only one which falls within the specified version range. Per NuGetVersion rules, a prerelease version is less than a stable version, so 4.0.1-preview is less than the 4.0.1 specified version so 4.0.1-preview does not fall within the specified version range and won't be returned.
+
+
+### Example 6
+```powershell
 PS C:\> Get-PSResource Az -Path .
 ```
 
 This will return all versions of the Az module that have been installed in the current directory.
 
-### Example 5
+### Example 7
 ```powershell
 PS C:\> Get-PSResource
 ```

help/Uninstall-PSResource.md

@@ -47,11 +47,24 @@ Uninstalls version 1.0.0 of the Az module.
 ### Example 3
 ```powershell
 PS C:\> Uninstall-PSResource -name Az -version "(1.0.0, 3.0.0)"
+```
 
 Uninstalls all versions within the specified version range.
+
+### Example 4
+```powershell
+PS C:\> Uninstall-PSResource -name Az -version "[4.0.1, 4.1.0]"
 ```
 
-Uninstalls version 1.0.0 of the Az module.
+Assume that the following versions are already installed for package Az: 4.0.1-preview, 4.1.0, 4.0.2-preview installed, this will uninstall all versions (stable and prerelease) which fall within the specified version range. Per NuGetVersion rules, a prerelease version is less than a stable version, so 4.0.1-preview is actually less than the 4.0.1 specified version so 4.0.1-preview does not fall within the specified version range and won't be removed. Versions 4.1.0 and 4.0.2-preview do fall in the range and will both be removed.
+
+### Example 4
+```powershell
+PS C:\> Uninstall-PSResource -name Az -version "[4.0.1, 4.1.0]" -Prerelease
+```
+
+Assume that the following versions are already installed for package Az: 4.0.1-preview, 4.1.0, 4.0.2-preview installed. This is the same example as above, except the added `-Prerelease` parameter means only prerelease versions which fall within this range will be removed. Again, per NuGetVersion rules, a prerelease version is less than a stable version, so 4.0.1-preview is actually less than the 4.0.1 specified version. Therefore 4.0.1-preview does not fall within the specified version range and won't be removed. Version 4.1.0 does fall in range however it is not a prerelease version so it will remain installed. Version 4.0.2-preview does fall in the range and is prerelease so it will be removed.
+
 
 ## PARAMETERS
 

src/code/GetHelper.cs

@@ -39,11 +39,12 @@ public GetHelper(PSCmdlet cmdletPassedIn)
         public IEnumerable<PSResourceInfo> GetPackagesFromPath(
             string[] name,
             VersionRange versionRange,
-            List<string> pathsToSearch)
+            List<string> pathsToSearch,
+            bool selectPrereleaseOnly)
         {
-            List<string> pgkPathsByName = FilterPkgPathsByName(name, pathsToSearch);
+            List<string> pkgPathsByName = FilterPkgPathsByName(name, pathsToSearch);
 
-            foreach (string pkgPath in FilterPkgPathsByVersion(versionRange, pgkPathsByName))
+            foreach (string pkgPath in FilterPkgPathsByVersion(versionRange, pkgPathsByName, selectPrereleaseOnly))
             {
                 PSResourceInfo pkg = OutputPackageObject(pkgPath, _scriptDictionary);
                 if (pkg != null)
@@ -77,7 +78,7 @@ public List<string> FilterPkgPathsByName(string[] names, List<string> dirsToSear
         }
 
         // Filter by user provided version
-        public IEnumerable<String> FilterPkgPathsByVersion(VersionRange versionRange, List<string> dirsToSearch)
+        public IEnumerable<String> FilterPkgPathsByVersion(VersionRange versionRange, List<string> dirsToSearch, bool selectPrereleaseOnly)
         {
             Dbg.Assert(versionRange != null, "Version Range cannot be null");
 
@@ -121,11 +122,15 @@ public IEnumerable<String> FilterPkgPathsByVersion(VersionRange versionRange, Li
 
                         _cmdletPassedIn.WriteVerbose(string.Format("Package version parsed as NuGet version: '{0}'", pkgNugetVersion));
 
+                        // For Uninstall-PSResource Prerelease parameter equates to selecting prerelease versions only to uninstall.
+                        // For other cmdlets (Find-PSResource, Install-PSResource) Prerelease parmater equates to selecting stable and prerelease versions.
+                        // We will not just select prerelase versions. For Get-PSResource, there is no Prerelease parameter.
                         if (versionRange.Satisfies(pkgNugetVersion))
                         {
-                            // This will be one version or a version range.
-                            // yield results then continue with this iteration of the loop
-                            yield return versionPath;
+                            if (!selectPrereleaseOnly || pkgNugetVersion.IsPrerelease)
+                            {
+                                yield return versionPath;
+                            }
                         }
                     }
                 }

src/code/GetPSResource.cs

@@ -128,7 +128,12 @@ protected override void ProcessRecord()
             }
 
             GetHelper getHelper = new GetHelper(this);
-            foreach (PSResourceInfo pkg in getHelper.GetPackagesFromPath(namesToSearch, _versionRange, _pathsToSearch))
+            // selectPrereleaseOnly is false because we want both stable and prerelease versions all the time.
+            foreach (PSResourceInfo pkg in getHelper.GetPackagesFromPath(
+                name: namesToSearch,
+                versionRange: _versionRange,
+                pathsToSearch: _pathsToSearch,
+                selectPrereleaseOnly: false))
             {
                 WriteObject(pkg);
             }

src/code/InstallHelper.cs

@@ -279,10 +279,12 @@ private IEnumerable<PSResourceInfo> FilterByInstalledPkgs(IEnumerable<PSResource
 
             GetHelper getHelper = new GetHelper(_cmdletPassedIn);
             // Get currently installed packages.
+            // selectPrereleaseOnly is false because even if Prerelease is true we want to include both stable and prerelease, never select prerelease only.
             IEnumerable<PSResourceInfo> pkgsAlreadyInstalled = getHelper.GetPackagesFromPath(
                 name: filteredPackages.Keys.ToArray(),
                 versionRange: _versionRange,
-                pathsToSearch: _pathsToSearch);
+                pathsToSearch: _pathsToSearch,
+                selectPrereleaseOnly: false);
             if (!pkgsAlreadyInstalled.Any())
             {
                 return packages;
@@ -666,7 +668,12 @@ private bool DetectClobber(string pkgName, Hashtable parsedMetadataHashtable)
             // Get installed modules, then get all possible paths
             bool foundClobber = false;
             GetHelper getHelper = new GetHelper(_cmdletPassedIn);
-            IEnumerable<PSResourceInfo> pkgsAlreadyInstalled = getHelper.GetPackagesFromPath(new string[] { "*" }, VersionRange.All, _pathsToSearch);
+            // selectPrereleaseOnly is false because even if Prerelease is true we want to include both stable and prerelease, never select prerelease only.
+            IEnumerable<PSResourceInfo> pkgsAlreadyInstalled = getHelper.GetPackagesFromPath(
+                name: new string[] { "*" },
+                versionRange: VersionRange.All,
+                pathsToSearch: _pathsToSearch,
+                selectPrereleaseOnly: false);
             // user parsed metadata hash
             List<string> listOfCmdlets = new List<string>();
             foreach (var cmdletName in parsedMetadataHashtable["CmdletsToExport"] as object[])

src/code/UninstallPSResource.cs

@@ -35,6 +35,12 @@ public sealed class UninstallPSResource : PSCmdlet
         [ValidateNotNullOrEmpty]
         public string Version { get; set; }
 
+        /// <summary>
+        /// When specified, only uninstalls prerelease versions.
+        /// </summary>
+        [Parameter]
+        public SwitchParameter Prerelease { get; set; }
+
         /// <summary>
         /// Used for pipeline input.
         /// </summary>
@@ -163,7 +169,7 @@ private bool UninstallPkgHelper()
             // note that the xml file is located in ./Scripts/InstalledScriptInfos, eg: ./Scripts/InstalledScriptInfos/TestScript_InstalledScriptInfo.xml
 
             string pkgName;
-            foreach (string pkgPath in getHelper.FilterPkgPathsByVersion(_versionRange, dirsToDelete))
+            foreach (string pkgPath in getHelper.FilterPkgPathsByVersion(_versionRange, dirsToDelete, selectPrereleaseOnly: Prerelease))
             {
                 pkgName = Utils.GetInstalledPackageName(pkgPath);
 

src/code/UpdatePSResource.cs

@@ -246,10 +246,13 @@ private string[] ProcessPackageNames(
             // Get all installed packages selected for updating.
             GetHelper getHelper = new GetHelper(cmdletPassedIn: this);
             var installedPackages = new Dictionary<string, PSResourceInfo>(StringComparer.InvariantCultureIgnoreCase);
+
+            // selectPrereleaseOnly is false because even if Prerelease is true we want to include both stable and prerelease, not select prerelease only.
             foreach (var installedPackage in getHelper.GetPackagesFromPath(
                 name: namesToProcess,
                 versionRange: VersionRange.All,
-                pathsToSearch: Utils.GetAllResourcePaths(this, Scope)))
+                pathsToSearch: Utils.GetAllResourcePaths(this, Scope),
+                selectPrereleaseOnly: false))
             {
                 if (!installedPackages.ContainsKey(installedPackage.Name))
                 {

test/UninstallPSResource.Tests.ps1

@@ -13,6 +13,7 @@ Describe 'Test Uninstall-PSResource for Modules' {
         $testScriptName = "test_script"
         Get-NewPSResourceRepositoryFile
         Uninstall-PSResource -name ContosoServer -Version "*"
+        Uninstall-PSResource -Name $testModuleName -Version "*"
     }
 
     BeforeEach {
@@ -183,6 +184,44 @@ Describe 'Test Uninstall-PSResource for Modules' {
         $res.Version | Should -Be "2.5.0.0"
     }
 
+    It "uninstall all prerelease versions (which satisfy the range) when -Version '*' and -Prerelease parameter is specified" {
+        Install-PSResource -Name $testModuleName -Version "3.0.0" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "3.5.2-beta001" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "4.0.0" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "4.5.2-alpha001" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "5.0.0" -Repository $TestGalleryName
+        $res = Get-PSResource -Name $testModuleName
+        $prereleaseVersionPkgs = $res | Where-Object {$_.IsPrerelease -eq $true}
+        $prereleaseVersionPkgs.Count | Should -Be 2
+
+        Uninstall-PSResource -Name $testModuleName -Version "*" -Prerelease
+        $res = Get-PSResource -Name $testModuleName
+        $prereleaseVersionPkgs = $res | Where-Object {$_.IsPrerelease -eq $true}
+        $prereleaseVersionPkgs.Count | Should -Be 0
+        $stableVersionPkgs = $res | Where-Object {$_.IsPrerelease -ne $true}
+        $stableVersionPkgs.Count | Should -Be 3
+    }
+
+    It "uninstall all prerelease versions (which satisfy the range) when -Version range and -Prerelease parameter is specified" {
+        Install-PSResource -Name $testModuleName -Version "3.0.0" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "3.5.2-beta001" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "4.0.0" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "4.5.2-alpha001" -Repository $TestGalleryName
+        Install-PSResource -Name $testModuleName -Version "5.0.0" -Repository $TestGalleryName
+        $res = Get-PSResource -Name $testModuleName
+        $prereleaseVersionPkgs = $res | Where-Object {$_.IsPrerelease -eq $true}
+        $prereleaseVersionPkgs.Count | Should -Be 2
+
+        Uninstall-PSResource -Name $testModuleName -Version "[3.0.0, 4.0.0]" -Prerelease
+        $res = Get-PSResource -Name $testModuleName
+        # should only uninstall 3.5.2-beta001, 4.5.2-alpha001 is out of range and should remain installed
+        $prereleaseVersionPkgs = $res | Where-Object {$_.IsPrerelease -eq $true}
+        $prereleaseVersionPkgs.Count | Should -Be 1
+        $stableVersionPkgs = $res | Where-Object {$_.IsPrerelease -ne $true}
+        # versions 3.0.0 and 4.0.0 fall in range but should not be uninstalled as Prerelease parameter only selects prerelease versions for uninstallation
+        $stableVersionPkgs.Count | Should -Be 3
+    }
+
     It "Uninstall module using -WhatIf, should not uninstall the module" {
         Uninstall-PSResource -Name "ContosoServer" -WhatIf
         $pkg = Get-Module ContosoServer -ListAvailable