Add documentation (loic-sharma#325)

chaghi · Sep 9, 2019 · 1b9da5b · 1b9da5b
1 parent 2c27656
commit 1b9da5b
Show file tree

Hide file tree

Showing 10 changed files with 206 additions and 62 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -11,3 +11,7 @@ You can run BaGet on your preferred platform:
 * [Azure](quickstart/azure.md)
 * [AWS](quickstart/aws.md)
 * [Google Cloud](quickstart/gcp.md)
+
+## BaGet SDK
+
+You can also use the [`BaGet.Protocol`](https://www.nuget.org/packages/BaGet.Protocol) package to interact with a NuGet server. For more information, please refer to the [BaGet SDK](tools/sdk.md) guide.
diff --git a/docs/tools/sdk.md b/docs/tools/sdk.md
@@ -0,0 +1,88 @@
+# BaGet SDK
+
+You can use BaGet's [`BaGet.Protocol`](https://www.nuget.org/packages/BaGet.Protocol) package to interact with a NuGet server.
+
+## Getting Started
+
+Install the [`BaGet.Protocol`](https://www.nuget.org/packages/BaGet.Protocol) package:
+
+```
+dotnet add package BaGet.Protocol
+```
+
+## List Package Versions
+
+Find all versions of the `Newtonsoft.Json` package:
+
+```csharp
+NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
+
+IReadOnlyList<NuGetVersion>> versions = await client.ListPackageVersionsAsync("Newtonsoft.Json");
+
+foreach (NuGetVersion version in versions)
+{
+    Console.WriteLine($"Found version: {version}");
+}
+```
+
+## Download a package
+
+```csharp
+NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
+
+string packageId = "Newtonsoft.Json";
+NuGetVersion packageVersion = new NuGetVersion("12.0.1");
+
+using (Stream packageStream = await client.GetPackageStreamAsync(packageId, packageVersion))
+{
+    Console.WriteLine($"Downloaded package {packageId} {packageVersion}");
+}
+```
+
+## Find Package Metadata
+
+```csharp
+NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
+
+// Find the metadata for all versions of a package.
+IReadOnlyList<PackageMetadata> items = await client.GetPackageMetadataAsync("Newtonsoft.Json");
+if (!items.Any())
+{
+    Console.WriteLine($"Package 'Newtonsoft.Json' does not exist");
+    return;
+}
+
+foreach (var metadata in items)
+{
+    Console.WriteLine($"Version: {metadata.Version}");
+    Console.WriteLine($"Listed: {metadata.Listed}");
+    Console.WriteLine($"Tags: {metadata.Tags}");
+    Console.WriteLine($"Description: {metadata.Description}");
+}
+
+// Or, find the metadata for a single version of a package.
+string packageId = "Newtonsoft.Json"
+NuGetVersion packageVersion = new NuGetVersion("12.0.1");
+
+PackageMetadata metadata = await client.GetPackageMetadataAsync(packageId, packageVersion);
+
+Console.WriteLine($"Listed: {metadata.Listed}");
+Console.WriteLine($"Tags: {metadata.Tags}");
+Console.WriteLine($"Description: {metadata.Description}");
+```
+
+## Search for packages
+
+Search for "json" packages:
+
+```csharp
+NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
+SearchResponse response = await client.SearchAsync("json");
+
+Console.WriteLine($"Found {response.TotalHits} total results");
+
+foreach (SearchResult searchResult in response.Data)
+{
+    Console.WriteLine($"Found package {searchResult.Id} {searchResult.Version}");
+}
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -44,6 +44,7 @@ pages:
   - Configuration: configuration.md
   - Tools:
     - Mirroring: tools/mirroring.md
+    - BaGet SDK: tools/sdk.md
   - BaGet vs. Other:
     - nuget.org: vs/nugetorg.md
     - NuGet.Server: vs/nugetserver.md

diff --git a/samples/Sample01_Download.cs b/samples/Sample01_Download.cs
@@ -1,4 +1,5 @@
 using System;
+using System.IO;
 using System.Threading.Tasks;
 using NuGet.Versioning;
 using Xunit;
@@ -11,12 +12,12 @@ public class Sample01_Download
         public async Task DownloadPackage()
         {
             // Downloads a package file (.nupkg)
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 
-            var packageId = "Newtonsoft.Json";
-            var packageVersion = new NuGetVersion("12.0.1");
+            string packageId = "Newtonsoft.Json";
+            NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-            using (var packageStream = await client.GetPackageStreamAsync(packageId, packageVersion))
+            using (Stream packageStream = await client.GetPackageStreamAsync(packageId, packageVersion))
             {
                 Console.WriteLine($"Downloaded package {packageId} {packageVersion}");
             }
@@ -26,12 +27,12 @@ public async Task DownloadPackage()
         public async Task DownloadPackageManifest()
         {
             // Downloads a package manifest (.nuspec)
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 
-            var packageId = "Newtonsoft.Json";
-            var packageVersion = new NuGetVersion("12.0.1");
+            string packageId = "Newtonsoft.Json";
+            NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-            using (var manifestStream = await client.GetPackageManifestStreamAsync(packageId, packageVersion))
+            using (Stream manifestStream = await client.GetPackageManifestStreamAsync(packageId, packageVersion))
             {
                 Console.WriteLine($"Downloaded package {packageId} {packageVersion}'s nuspec");
             }

diff --git a/samples/Sample02_Search.cs b/samples/Sample02_Search.cs
@@ -10,13 +10,13 @@ public class Sample02_Search
         public async Task Search()
         {
             // Search for packages that are relevant to "json".
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
-            var response = await client.SearchAsync("json");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            SearchResponse response = await client.SearchAsync("json");
 
             Console.WriteLine($"Found {response.TotalHits} results");
 
             var index = 1;
-            foreach (var searchResult in response.Data)
+            foreach (SearchResult searchResult in response.Data)
             {
                 Console.WriteLine($"Result #{index}");
                 Console.WriteLine($"Package id: {searchResult.PackageId}");
@@ -33,15 +33,15 @@ public async Task Search()
         public async Task Autocomplete()
         {
             // Search for packages whose names' start with "Newt".
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
-            var response = await client.AutocompleteAsync("Newt");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            AutocompleteResponse response = await client.AutocompleteAsync("Newt");
 
             Console.WriteLine($"Found {response.TotalHits} results");
 
             var index = 1;
-            foreach (var searchResult in response.Data)
+            foreach (string packageId in response.Data)
             {
-                Console.WriteLine($"Result #{index}: '{searchResult}'");
+                Console.WriteLine($"Found package ID #{index}: '{packageId}'");
                 index++;
             }
         }

diff --git a/samples/Sample03_Metadata.cs b/samples/Sample03_Metadata.cs
@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
@@ -13,48 +14,48 @@ public class Sample03_Metadata
         public async Task GetAllPackageMetadata()
         {
             // Find the metadata for all versions of a package.
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 
-            var items = await client.GetPackageMetadataAsync("Newtonsoft.Json");
+            IReadOnlyList<PackageMetadata> items = await client.GetPackageMetadataAsync("Newtonsoft.Json");
             if (!items.Any())
             {
                 Console.WriteLine($"Package 'Newtonsoft.Json' does not exist");
                 return;
             }
 
             // There is an item for each version of the package.
-            foreach (var item in items)
+            foreach (var metadata in items)
             {
-                Console.WriteLine($"Version: {item.PackageMetadata.Version}");
-                Console.WriteLine($"Listed: {item.PackageMetadata.Listed}");
-                Console.WriteLine($"Tags: {item.PackageMetadata.Tags}");
-                Console.WriteLine($"Description: {item.PackageMetadata.Description}");
+                Console.WriteLine($"Version: {metadata.Version}");
+                Console.WriteLine($"Listed: {metadata.Listed}");
+                Console.WriteLine($"Tags: {metadata.Tags}");
+                Console.WriteLine($"Description: {metadata.Description}");
             }
         }
 
         [Fact]
         public async Task GetPackageMetadata()
         {
             // Find the metadata for a single version of a package.
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 
-            var packageId = "Newtonsoft.Json";
-            var packageVersion = new NuGetVersion("12.0.1");
+            string packageId = "Newtonsoft.Json";
+            NuGetVersion packageVersion = new NuGetVersion("12.0.1");
 
-            var registrationItem = await client.GetPackageMetadataAsync(packageId, packageVersion);
+            PackageMetadata metadata = await client.GetPackageMetadataAsync(packageId, packageVersion);
 
-            Console.WriteLine($"Listed: {registrationItem.PackageMetadata.Listed}");
-            Console.WriteLine($"Tags: {registrationItem.PackageMetadata.Tags}");
-            Console.WriteLine($"Description: {registrationItem.PackageMetadata.Description}");
+            Console.WriteLine($"Listed: {metadata.Listed}");
+            Console.WriteLine($"Tags: {metadata.Tags}");
+            Console.WriteLine($"Description: {metadata.Description}");
         }
 
         [Fact]
         public async Task ListVersions()
         {
             // Find all versions of a package (including unlisted versions).
-            var client = new NuGetClient("https://api.nuget.org/v3/index.json");
+            NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json");
 
-            var packageVersions = await client.ListPackageVersions("Newtonsoft.Json", includeUnlisted: true);
+            IReadOnlyList<NuGetVersion> packageVersions = await client.ListPackageVersionsAsync("Newtonsoft.Json", includeUnlisted: true);
             if (!packageVersions.Any())
             {
                 Console.WriteLine($"Package 'Newtonsoft.Json' does not exist");

diff --git a/src/BaGet.Core/Mirror/MirrorService.cs b/src/BaGet.Core/Mirror/MirrorService.cs
@@ -39,7 +39,7 @@ public async Task<IReadOnlyList<NuGetVersion>> FindPackageVersionsOrNullAsync(
             string id,
             CancellationToken cancellationToken)
         {
-            var upstreamVersions = await _upstreamClient.ListPackageVersions(id, includeUnlisted: true, cancellationToken);
+            var upstreamVersions = await _upstreamClient.ListPackageVersionsAsync(id, includeUnlisted: true, cancellationToken);
             if (!upstreamVersions.Any())
             {
                 return null;
@@ -101,10 +101,8 @@ public async Task MirrorAsync(string id, NuGetVersion version, CancellationToken
                 version);
         }
 
-        private Package ToPackage(RegistrationIndexPageItem item)
+        private Package ToPackage(PackageMetadata metadata)
         {
-            var metadata = item.PackageMetadata;
-
             return new Package
             {
                 Id = metadata.PackageId,

diff --git a/src/BaGet.Protocol/INuGetClient.cs b/src/BaGet.Protocol/INuGetClient.cs
@@ -47,7 +47,7 @@ Task<Stream> GetPackageManifestStreamAsync(
         /// <param name="packageId">The package ID.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's listed versions, if any.</returns>
-        Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(
+        Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(
             string packageId,
             CancellationToken cancellationToken);
 
@@ -58,7 +58,7 @@ Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(
         /// <param name="includeUnlisted">Whether to include unlisted versions.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's versions, or an empty list if the package does not exist.</returns>
-        Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(
+        Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(
             string packageId,
             bool includeUnlisted,
             CancellationToken cancellationToken = default);
@@ -69,7 +69,7 @@ Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(
         /// <param name="packageId">The package ID.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's metadata, or an empty list if the package does not exist.</returns>
-        Task<IReadOnlyList<RegistrationIndexPageItem>> GetPackageMetadataAsync(
+        Task<IReadOnlyList<PackageMetadata>> GetPackageMetadataAsync(
             string packageId,
             CancellationToken cancellationToken = default);
 
@@ -83,7 +83,7 @@ Task<IReadOnlyList<RegistrationIndexPageItem>> GetPackageMetadataAsync(
         /// <exception cref="PackageNotFoundException">
         ///     The package could not be found.
         /// </exception>
-        Task<RegistrationIndexPageItem> GetPackageMetadataAsync(
+        Task<PackageMetadata> GetPackageMetadataAsync(
             string packageId,
             NuGetVersion packageVersion,
             CancellationToken cancellationToken = default);

diff --git a/src/BaGet.Protocol/NuGetClient.cs b/src/BaGet.Protocol/NuGetClient.cs
@@ -92,14 +92,14 @@ public async Task<Stream> GetPackageManifestStreamAsync(string packageId, NuGetV
         /// <param name="packageId">The package ID.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's listed versions, if any.</returns>
-        public async Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(string packageId, CancellationToken cancellationToken)
+        public async Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(string packageId, CancellationToken cancellationToken)
         {
             // TODO: Use the Autocomplete's enumerate versions endpoint if this is not Sleet.
             var packages = await GetPackageMetadataAsync(packageId, cancellationToken);
 
             return packages
-                .Where(p => p.PackageMetadata.Listed)
-                .Select(p => p.PackageMetadata.Version)
+                .Where(p => p.Listed)
+                .Select(p => p.Version)
                 .ToList();
         }
 
@@ -110,11 +110,11 @@ public async Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(string packag
         /// <param name="includeUnlisted">Whether to include unlisted versions.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's versions, or an empty list if the package does not exist.</returns>
-        public async Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(string packageId, bool includeUnlisted, CancellationToken cancellationToken = default)
+        public async Task<IReadOnlyList<NuGetVersion>> ListPackageVersionsAsync(string packageId, bool includeUnlisted, CancellationToken cancellationToken = default)
         {
             if (!includeUnlisted)
             {
-                return await ListPackageVersions(packageId, cancellationToken);
+                return await ListPackageVersionsAsync(packageId, cancellationToken);
             }
 
             var client = await _clientFactory.CreatePackageContentClientAsync(cancellationToken);
@@ -134,9 +134,9 @@ public async Task<IReadOnlyList<NuGetVersion>> ListPackageVersions(string packag
         /// <param name="packageId">The package ID.</param>
         /// <param name="cancellationToken">A token to cancel the task.</param>
         /// <returns>The package's metadata, or an empty list if the package does not exist.</returns>
-        public async Task<IReadOnlyList<RegistrationIndexPageItem>> GetPackageMetadataAsync(string packageId, CancellationToken cancellationToken = default)
+        public async Task<IReadOnlyList<PackageMetadata>> GetPackageMetadataAsync(string packageId, CancellationToken cancellationToken = default)
         {
-            var result = new List<RegistrationIndexPageItem>();
+            var result = new List<PackageMetadata>();
 
             var client = await _clientFactory.CreatePackageMetadataClientAsync(cancellationToken);
             var registrationIndex = await client.GetRegistrationIndexOrNullAsync(packageId, cancellationToken);
@@ -166,7 +166,7 @@ public async Task<IReadOnlyList<RegistrationIndexPageItem>> GetPackageMetadataAs
                     items = externalRegistrationPage.ItemsOrNull;
                 }
 
-                result.AddRange(items);
+                result.AddRange(items.Select(i => i.PackageMetadata));
             }
 
             return result;
@@ -182,7 +182,7 @@ public async Task<IReadOnlyList<RegistrationIndexPageItem>> GetPackageMetadataAs
         /// <exception cref="PackageNotFoundException">
         ///     The package could not be found.
         /// </exception>
-        public async Task<RegistrationIndexPageItem> GetPackageMetadataAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default)
+        public async Task<PackageMetadata> GetPackageMetadataAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default)
         {
             var client = await _clientFactory.CreatePackageMetadataClientAsync(cancellationToken);
             var registrationIndex = await client.GetRegistrationIndexOrNullAsync(packageId, cancellationToken);
@@ -192,7 +192,6 @@ public async Task<RegistrationIndexPageItem> GetPackageMetadataAsync(string pack
                 throw new PackageNotFoundException(packageId, packageVersion);
             }
 
-            var result = new List<RegistrationIndexPageItem>();
             foreach (var registrationIndexPage in registrationIndex.Pages)
             {
                 // Skip pages that do not contain the desired package version.
@@ -217,7 +216,14 @@ public async Task<RegistrationIndexPageItem> GetPackageMetadataAsync(string pack
                     items = externalRegistrationPage.ItemsOrNull;
                 }
 
-                return items.SingleOrDefault(i => i.PackageMetadata.Version == packageVersion);
+                // We've found the registration items that should cover the desired package.
+                var result = items.SingleOrDefault(i => i.PackageMetadata.Version == packageVersion);
+                if (result == null)
+                {
+                    break;
+                }
+
+                return result.PackageMetadata;
             }
 
             // No registration pages contained the desired version.