From 963e5702b8fdc10689d0e25a434431698d761310 Mon Sep 17 00:00:00 2001 From: Andy Zivkovic Date: Fri, 11 Oct 2024 07:26:51 +1030 Subject: [PATCH 1/4] Add XMLDoc comments on public PackageExtractor methods --- .../NuGet.Packaging/PackageExtractor.cs | 61 ++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs b/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs index 7ec6b235585..b84c56acf24 100644 --- a/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs +++ b/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs @@ -17,6 +17,18 @@ namespace NuGet.Packaging { public static class PackageExtractor { + /// + /// Extracts a package, using the packages.config directory layout + /// + /// For PackageReference directory layout, use + /// The source from which the package was downloaded + /// A for the nupkg file that is being extracted. + /// The V2 (packages.config) . + /// The with settings for how the extraction should be configured. + /// A cancellation token. + /// Telemetry parent ID. + /// A collection of files that were extracted. + /// If packageReader, packagePathResolver, or packageExtractionContext are null. public static async Task> ExtractPackageAsync( string source, Stream packageStream, @@ -140,6 +152,19 @@ await VerifyPackageSignatureAsync( } } + /// + /// Extracts a package, using the packages.config directory layout + /// + /// For PackageReference directory layout, use + /// The source from which the package was downloaded + /// A with the package opened. + /// A for the nupkg file that is being extracted. + /// The V2 (packages.config) . + /// The with settings for how the extraction should be configured. + /// A cancellation token. + /// Telemetry parent ID. + /// A collection of files that were extracted. + /// If packageReader, packagePathResolver, or packageExtractionContext are null. public static async Task> ExtractPackageAsync( string source, PackageReaderBase packageReader, @@ -241,6 +266,18 @@ await VerifyPackageSignatureAsync( } } + /// + /// Extracts a package, using the packages.config directory layout + /// + /// For PackageReference directory layout, use + /// The source from which the package was downloaded + /// A with the package opened. + /// The V2 (packages.config) . + /// The with settings for how the extraction should be configured. + /// A cancellation token. + /// Telemetry parent ID. + /// A collection of files that were extracted. + /// If packageReader, packagePathResolver, or packageExtractionContext are null. public static async Task> ExtractPackageAsync( string source, PackageReaderBase packageReader, @@ -336,16 +373,20 @@ await VerifyPackageSignatureAsync( } /// - /// Uses a copy function to install a package to a global packages directory. + /// Uses a copy function to install a package to a global packages directory with the PackageReference directory layout. /// + /// The source where the nupkg was downloaded from. + /// The package id + version being installed. /// /// A function which should copy the package to the provided destination stream. /// + /// The path resolver for PackageReference layout. /// /// The version folder path context, which encapsulates all of the parameters to observe /// while installing the package. /// /// The cancellation token. + /// The telemetry parent ID. /// /// True if the package was installed. False if the package already exists and therefore /// resulted in no copy operation. @@ -592,6 +633,24 @@ private static void DeleteTargetAndTempPaths(string targetPath, string targetTem } } + /// + /// Uses a copy function to install a package to a global packages directory with the PackageReference directory layout. + /// + /// The package id + version being installed. + /// + /// A to download the nupkg. + /// + /// The path resolver for PackageReference layout. + /// + /// The version folder path context, which encapsulates all of the parameters to observe + /// while installing the package. + /// + /// The cancellation token. + /// The telemetry parent ID. + /// + /// True if the package was installed. False if the package already exists and therefore + /// resulted in no copy operation. + /// public static async Task InstallFromSourceAsync( PackageIdentity packageIdentity, IPackageDownloader packageDownloader, From 5cb3279565f30df131b15d0ca2245bb7d2fe3a84 Mon Sep 17 00:00:00 2001 From: Andy Zivkovic Date: Wed, 16 Oct 2024 10:33:43 +1030 Subject: [PATCH 2/4] feedback --- src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs b/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs index b84c56acf24..4a888d9db8c 100644 --- a/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs +++ b/src/NuGet.Core/NuGet.Packaging/PackageExtractor.cs @@ -29,6 +29,8 @@ public static class PackageExtractor /// Telemetry parent ID. /// A collection of files that were extracted. /// If packageReader, packagePathResolver, or packageExtractionContext are null. + /// If packageStream is not seekable. + /// If the package signature couldn't be validated. See exception message for more details. public static async Task> ExtractPackageAsync( string source, Stream packageStream, @@ -165,6 +167,8 @@ await VerifyPackageSignatureAsync( /// Telemetry parent ID. /// A collection of files that were extracted. /// If packageReader, packagePathResolver, or packageExtractionContext are null. + /// If packagestream is not seekable. + /// If the package signature couldn't be validated. See exception message for more details. public static async Task> ExtractPackageAsync( string source, PackageReaderBase packageReader, @@ -278,6 +282,7 @@ await VerifyPackageSignatureAsync( /// Telemetry parent ID. /// A collection of files that were extracted. /// If packageReader, packagePathResolver, or packageExtractionContext are null. + /// If the package signature couldn't be validated. See exception message for more details. public static async Task> ExtractPackageAsync( string source, PackageReaderBase packageReader, @@ -391,6 +396,8 @@ await VerifyPackageSignatureAsync( /// True if the package was installed. False if the package already exists and therefore /// resulted in no copy operation. /// + /// If copyToAsync or packageExtractionContext is null. + /// If the package signature couldn't be validated. See exception message for more details. public static async Task InstallFromSourceAsync( string source, PackageIdentity packageIdentity, @@ -651,6 +658,8 @@ private static void DeleteTargetAndTempPaths(string targetPath, string targetTem /// True if the package was installed. False if the package already exists and therefore /// resulted in no copy operation. /// + /// If packageDownlaoder or packageExtractionContext is null. + /// If the package signature couldn't be validated. See exception message for more details. public static async Task InstallFromSourceAsync( PackageIdentity packageIdentity, IPackageDownloader packageDownloader, From 5e64add3f609f4c1ecaaa87e57476543db2a1b79 Mon Sep 17 00:00:00 2001 From: Andy Zivkovic Date: Thu, 17 Oct 2024 08:13:14 +1030 Subject: [PATCH 3/4] Improve comments on path resolver classes too --- src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs | 3 ++- src/NuGet.Core/NuGet.Packaging/VersionFolderPathResolver.cs | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs b/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs index faeed617022..44b6ccbe08e 100644 --- a/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs +++ b/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs @@ -19,8 +19,9 @@ public class PackagePathResolver public bool UseSideBySidePaths { get; } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class, which calculates packages.config style package directory layouts. /// + /// See for PackageReference & global packages folder layouts. /// The root directory. /// A value indicating whether to use side-by-side paths. /// If rootDirectory is null, empty or does not contain an absolute path. diff --git a/src/NuGet.Core/NuGet.Packaging/VersionFolderPathResolver.cs b/src/NuGet.Core/NuGet.Packaging/VersionFolderPathResolver.cs index 55232af2b33..105e34c5c23 100644 --- a/src/NuGet.Core/NuGet.Packaging/VersionFolderPathResolver.cs +++ b/src/NuGet.Core/NuGet.Packaging/VersionFolderPathResolver.cs @@ -8,7 +8,7 @@ namespace NuGet.Packaging { /// - /// A V3 path resolver. + /// A path resolver to calculate package paths for PackageReference (Global Packages Folder) style directory layouts. /// public class VersionFolderPathResolver { From 3230c357425df0237f70a7a03a54fa6e283f6f54 Mon Sep 17 00:00:00 2001 From: Andy Zivkovic Date: Thu, 17 Oct 2024 22:03:10 +1030 Subject: [PATCH 4/4] Fix syntax --- src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs b/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs index 44b6ccbe08e..42ff6e813fe 100644 --- a/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs +++ b/src/NuGet.Core/NuGet.Packaging/PackagePathResolver.cs @@ -21,7 +21,7 @@ public class PackagePathResolver /// /// Initializes a new instance of the class, which calculates packages.config style package directory layouts. /// - /// See for PackageReference & global packages folder layouts. + /// See for PackageReference and global packages folder layouts. /// The root directory. /// A value indicating whether to use side-by-side paths. /// If rootDirectory is null, empty or does not contain an absolute path.