From 79c8d04dd97ae69fc695bb0a2a8135737518b5c8 Mon Sep 17 00:00:00 2001 From: Anam Navied Date: Thu, 15 Sep 2022 11:20:28 -0400 Subject: [PATCH 1/3] update IInstallPSResource and IFindPSResource with API calls --- src/code/IFindPSResource.cs | 43 ++++++++++++++++++++++------------ src/code/IInstallPSResource.cs | 4 ++++ 2 files changed, 32 insertions(+), 15 deletions(-) diff --git a/src/code/IFindPSResource.cs b/src/code/IFindPSResource.cs index 3b0406836..633d30964 100644 --- a/src/code/IFindPSResource.cs +++ b/src/code/IFindPSResource.cs @@ -28,32 +28,39 @@ public interface IFindPSResource /// Name: supports wildcards /// Type: Module, Script, Command, DSCResource (can take multiple) /// Examples: Search -Type Module -Repository PSGallery - /// Search "Az*" -Type Module -Repository PSGallery - /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='tag:Module' - /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='tag:Module'&includePrerelease=true + /// Search -Type Module -Name "Az*" -Repository PSGallery + /// TODO: discuss consolidating Modules and Scripts endpoints (move scripts to modules endpoint) + /// TODO Note: searchTerm is tokenized by whitespace. + /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSModule' + /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='az* tag:PSScript'&includePrerelease=true /// PSResourceInfo FindTypes(ResourceType packageResourceType, string packageName, PSRepositoryInfo repository, bool includePrerelease); /// /// Find method which allows for searching for command names and returns latest version of matching packages. - /// Name: supports wildcards + /// Name: no wildcard support /// Examples: Search -Name "Command1", "Command2" -Repository PSGallery + /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSCommand_Command1 tag:PSCommand_Command2' + /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSCommand_Command1 tag:PSCommand_Command2'&includePrerelease=true /// PSResourceInfo FindCommandName(string[] commandNames, PSRepositoryInfo repository, bool includePrerelease); /// /// Find method which allows for searching for DSC Resource names and returns latest version of matching packages. - /// Name: supports wildcards + /// Name: no wildcard support /// Examples: Search -Name "DSCResource1", "DSCResource2" -Repository PSGallery - PSResourceInfo FindDSCResourceName(string[] dscResourceName, PSRepositoryInfo repository, bool includePrerPSResourceInfoPSResourceInfoelease); + /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSDSCResource_DSCResource1 tag:PSDSCResource_DSCResource2' + /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSDSCResource_DSCResource1 tag:PSDSCResource_DSCResource2'&includePrerelease=true + PSResourceInfo FindDSCResourceName(string[] dscResourceName, PSRepositoryInfo repository, bool includePrerelease); /// /// Find method which allows for searching for single name and returns latest version. /// Name: no wildcard support /// Examples: Search "PowerShellGet" /// API call: - /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='PowerShellGet' - /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='PowerShellGet'&includePrerelease=true + /// - No prerelease: http://www.powershellgallery.com/api/v2/FindPackagesById()?id='PowerShellGet' + /// - Include prerelease: http://www.powershellgallery.com/api/v2/FindPackagesById()?id='PowerShellGet' + /// Implementation Note: Need to filter further for latest version (prerelease or non-prerelease dependening on user preference) /// PSResourceInfo FindName(string packageName, PSRepositoryInfo repository, bool includePrerelease); @@ -64,6 +71,7 @@ public interface IFindPSResource /// API call: /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='az*' /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='az*'&includePrerelease=true + /// Implementation Note: filter additionally and verify ONLY package name was a match. /// PSResourceInfo FindNameGlobbing(string packageName, PSRepositoryInfo repository, bool includePrerelease); @@ -73,6 +81,8 @@ public interface IFindPSResource /// Version: supports wildcards /// Examples: Search "PowerShellGet" "[3.0.0.0, 5.0.0.0]" /// Search "PowerShellGet" "3.*" + /// API Call: http://www.powershellgallery.com/api/v2/FindPackagesById()?id='PowerShellGet' + /// Implementation note: Returns all versions, including prerelease ones. Later (in the API client side) we'll do filtering on the versions to satisfy what user provided. /// PSResourceInfo FindVersionGlobbing(string packageName, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease); @@ -84,8 +94,9 @@ public interface IFindPSResource /// API call: http://www.powershellgallery.com/api/v2/Packages(Id='PowerShellGet', Version='2.2.5') /// PSResourceInfo FindVersion(string packageName, NuGetVersion version, PSRepositoryInfo repository); - + /// + /// *** we will not support this scenario *** /// Find method which allows for searching for single name with wildcards with version range. /// Name: supports wildcards /// Version: support wildcards @@ -95,6 +106,7 @@ public interface IFindPSResource PSResourceInfo FindNameGlobbingAndVersionGlobbing(string packageName, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease); /// + /// *** we will not support this scenario *** /// Find method which allows for searching for single name with wildcards with specific version. /// Name: supports wildcards /// Version: no wildcard support @@ -103,16 +115,15 @@ public interface IFindPSResource PSResourceInfo FindNameGlobbingAndVersion(string packageName, NuGetVersion version, PSRepositoryInfo repository); /// + /// *** Note: we would just iterate through the names client side and call FindName() or FindNameGlobbing() *** /// Find method which allows for searching for multiple names and returns latest version for each. /// Name: supports wildcards /// Examples: Search "PowerShellGet", "Package*", "PSReadLine" - /// API call: - /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='PSReadLine, Package*' - /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsAbsoluteLatestVersion&searchTerm='PSReadLine, Package*'&includePrerelease=true /// PSResourceInfo FindNamesGlobbing(string[] packageNames, PSRepositoryInfo repository, bool includePrerelease); /// + /// *** we will not support this scenario *** /// Find method which allows for searching for multiple names with specific version. /// Name: supports wildcards /// Version: no wildcard support @@ -121,13 +132,15 @@ public interface IFindPSResource PSResourceInfo FindNamesGlobbingAndVersion(string[] packageNames, NuGetVersion version, PSRepositoryInfo repository); /// + /// *** Note: would just iterate through names client side, and call FindVersionGlobbing() for each and discard (error) for name with globbing) *** /// Find method which allows for searching for multiple names with version range. /// Name: supports wildcards /// Version: support wildcards - /// Examples: Search "PowerShellGet", "Package*", "PSReadLine" "[3.0.0.0, 5.0.0.0]" - /// Search "PowerShellGet", "Package*", "PSReadLine" "3.*" + /// Examples: Search "PowerShellGet", "Package*", "PSReadLine" "[3.0.0.0, 5.0.0.0]" --> do it for first, write error for second, do it for third + /// Search "PowerShellGet", "Package*", "PSReadLine" "3.*" --> do it for first, write error for second, do it for third + /// Search "Package*", "PSReadLin*" "3.*" --> not supported /// - PSResourceInfo FindNamesGlobbingAndVersionGlobbing(string[] packageNames, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease); + PSResourceInfo FindNamesAndVersionGlobbing(string[] packageNames, VersionRange versionRange, PSRepositoryInfo repository, bool includePrerelease); #endregion } diff --git a/src/code/IInstallPSResource.cs b/src/code/IInstallPSResource.cs index 4c9ac365e..ebdc741f1 100644 --- a/src/code/IInstallPSResource.cs +++ b/src/code/IInstallPSResource.cs @@ -9,6 +9,8 @@ public interface IInstallPSResource /// Installs specific package. /// Name: no wildcard support. /// Examples: Install "PowerShellGet" + /// Implementation Note: if prerelease: call IFindPSResource.FindName() + /// if not prerelease: https://www.powershellgallery.com/api/v2/package/Id (Returns latest stable) /// PSResourceInfo InstallName(string pkgName, PSRepositoryInfo repository, bool includePrerelease); @@ -18,10 +20,12 @@ public interface IInstallPSResource /// Version: no wildcard support. /// Examples: Install "PowerShellGet" -Version "3.0.0.0" /// Install "PowerShellGet" -Version "3.0.0-beta16" + /// API Call: https://www.powershellgallery.com/api/v2/package/Id/version (version can be prerelease) /// PSResourceInfo InstallVersion(string pkgName, NuGetVersion version, PSRepositoryInfo repository); /// + /// Implementation note: We'd call IFindPSResource.FindVersionGlobbing() first and InstallVersion(). /// Installs latest package within version range provided. /// Name: no wildcard support. /// Version: supports wilcard. From 94c9a9670c3918f4167adcc7d6bab77e7694ffe1 Mon Sep 17 00:00:00 2001 From: Anam Navied Date: Thu, 15 Sep 2022 11:27:24 -0400 Subject: [PATCH 2/3] Update src/code/IFindPSResource.cs --- src/code/IFindPSResource.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/code/IFindPSResource.cs b/src/code/IFindPSResource.cs index 633d30964..e22005264 100644 --- a/src/code/IFindPSResource.cs +++ b/src/code/IFindPSResource.cs @@ -38,7 +38,7 @@ public interface IFindPSResource /// /// Find method which allows for searching for command names and returns latest version of matching packages. - /// Name: no wildcard support + /// Name: supports wildcards. /// Examples: Search -Name "Command1", "Command2" -Repository PSGallery /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSCommand_Command1 tag:PSCommand_Command2' /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSCommand_Command1 tag:PSCommand_Command2'&includePrerelease=true From 60143f5656a11d9eb61c19a4b38cddf64acf38d7 Mon Sep 17 00:00:00 2001 From: Anam Navied Date: Thu, 15 Sep 2022 11:27:54 -0400 Subject: [PATCH 3/3] Update src/code/IFindPSResource.cs --- src/code/IFindPSResource.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/code/IFindPSResource.cs b/src/code/IFindPSResource.cs index e22005264..986df5ec8 100644 --- a/src/code/IFindPSResource.cs +++ b/src/code/IFindPSResource.cs @@ -47,7 +47,7 @@ public interface IFindPSResource /// /// Find method which allows for searching for DSC Resource names and returns latest version of matching packages. - /// Name: no wildcard support + /// Name: Support wildcards. /// Examples: Search -Name "DSCResource1", "DSCResource2" -Repository PSGallery /// - No prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSDSCResource_DSCResource1 tag:PSDSCResource_DSCResource2' /// - Include prerelease: http://www.powershellgallery.com/api/v2/Search()?$filter=IsLatestVersion&searchTerm='Az* tag:PSDSCResource_DSCResource1 tag:PSDSCResource_DSCResource2'&includePrerelease=true