From 1b9da5ba74ba2ec0362424ac75ae19ff7bd7b783 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Sharma?= Date: Sun, 8 Sep 2019 22:40:01 -0700 Subject: [PATCH] Add documentation (#325) --- docs/index.md | 4 ++ docs/tools/sdk.md | 88 ++++++++++++++++++++++++++ mkdocs.yml | 1 + samples/Sample01_Download.cs | 17 ++--- samples/Sample02_Search.cs | 14 ++-- samples/Sample03_Metadata.cs | 33 +++++----- src/BaGet.Core/Mirror/MirrorService.cs | 6 +- src/BaGet.Protocol/INuGetClient.cs | 8 +-- src/BaGet.Protocol/NuGetClient.cs | 28 ++++---- src/BaGet.Protocol/readme.md | 69 ++++++++++++++++---- 10 files changed, 206 insertions(+), 62 deletions(-) create mode 100644 docs/tools/sdk.md diff --git a/docs/index.md b/docs/index.md index 6a216d82..7a1e9722 100644 --- 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 new file mode 100644 index 00000000..c5f8d91a --- /dev/null +++ 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> 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 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 index aff28456..08056edd 100644 --- 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 index 40d16287..e1d21273 100644 --- 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 index d62f59bf..e75b9650 100644 --- 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 index 2bde67f9..b3ea24e2 100644 --- 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,9 +14,9 @@ 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 items = await client.GetPackageMetadataAsync("Newtonsoft.Json"); if (!items.Any()) { Console.WriteLine($"Package 'Newtonsoft.Json' does not exist"); @@ -23,12 +24,12 @@ public async Task GetAllPackageMetadata() } // 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}"); } } @@ -36,25 +37,25 @@ public async Task GetAllPackageMetadata() 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 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 index 68f530e2..a8851fa4 100644 --- a/src/BaGet.Core/Mirror/MirrorService.cs +++ b/src/BaGet.Core/Mirror/MirrorService.cs @@ -39,7 +39,7 @@ public async Task> 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 index 75f76dbb..e04d0154 100644 --- a/src/BaGet.Protocol/INuGetClient.cs +++ b/src/BaGet.Protocol/INuGetClient.cs @@ -47,7 +47,7 @@ Task GetPackageManifestStreamAsync( /// The package ID. /// A token to cancel the task. /// The package's listed versions, if any. - Task> ListPackageVersions( + Task> ListPackageVersionsAsync( string packageId, CancellationToken cancellationToken); @@ -58,7 +58,7 @@ Task> ListPackageVersions( /// Whether to include unlisted versions. /// A token to cancel the task. /// The package's versions, or an empty list if the package does not exist. - Task> ListPackageVersions( + Task> ListPackageVersionsAsync( string packageId, bool includeUnlisted, CancellationToken cancellationToken = default); @@ -69,7 +69,7 @@ Task> ListPackageVersions( /// The package ID. /// A token to cancel the task. /// The package's metadata, or an empty list if the package does not exist. - Task> GetPackageMetadataAsync( + Task> GetPackageMetadataAsync( string packageId, CancellationToken cancellationToken = default); @@ -83,7 +83,7 @@ Task> GetPackageMetadataAsync( /// /// The package could not be found. /// - Task GetPackageMetadataAsync( + Task GetPackageMetadataAsync( string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default); diff --git a/src/BaGet.Protocol/NuGetClient.cs b/src/BaGet.Protocol/NuGetClient.cs index d54b360d..a0ef3985 100644 --- a/src/BaGet.Protocol/NuGetClient.cs +++ b/src/BaGet.Protocol/NuGetClient.cs @@ -92,14 +92,14 @@ public async Task GetPackageManifestStreamAsync(string packageId, NuGetV /// The package ID. /// A token to cancel the task. /// The package's listed versions, if any. - public async Task> ListPackageVersions(string packageId, CancellationToken cancellationToken) + public async Task> 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> ListPackageVersions(string packag /// Whether to include unlisted versions. /// A token to cancel the task. /// The package's versions, or an empty list if the package does not exist. - public async Task> ListPackageVersions(string packageId, bool includeUnlisted, CancellationToken cancellationToken = default) + public async Task> 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> ListPackageVersions(string packag /// The package ID. /// A token to cancel the task. /// The package's metadata, or an empty list if the package does not exist. - public async Task> GetPackageMetadataAsync(string packageId, CancellationToken cancellationToken = default) + public async Task> GetPackageMetadataAsync(string packageId, CancellationToken cancellationToken = default) { - var result = new List(); + var result = new List(); var client = await _clientFactory.CreatePackageMetadataClientAsync(cancellationToken); var registrationIndex = await client.GetRegistrationIndexOrNullAsync(packageId, cancellationToken); @@ -166,7 +166,7 @@ public async Task> GetPackageMetadataAs items = externalRegistrationPage.ItemsOrNull; } - result.AddRange(items); + result.AddRange(items.Select(i => i.PackageMetadata)); } return result; @@ -182,7 +182,7 @@ public async Task> GetPackageMetadataAs /// /// The package could not be found. /// - public async Task GetPackageMetadataAsync(string packageId, NuGetVersion packageVersion, CancellationToken cancellationToken = default) + public async Task 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 GetPackageMetadataAsync(string pack throw new PackageNotFoundException(packageId, packageVersion); } - var result = new List(); foreach (var registrationIndexPage in registrationIndex.Pages) { // Skip pages that do not contain the desired package version. @@ -217,7 +216,14 @@ public async Task 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. diff --git a/src/BaGet.Protocol/readme.md b/src/BaGet.Protocol/readme.md index aa786081..53d7d3f2 100644 --- a/src/BaGet.Protocol/readme.md +++ b/src/BaGet.Protocol/readme.md @@ -2,7 +2,7 @@ BaGet's SDK to interact with the [NuGet protocol](https://docs.microsoft.com/en-us/nuget/api/overview). -[Package (NuGet)](https://www.nuget.org/packages/BaGet.Protocol) | Documentation | [Samples](https://github.com/loic-sharma/BaGet/tree/master/samples) +[Package (NuGet)](https://www.nuget.org/packages/BaGet.Protocol) | [Documentation](https://loic-sharma.github.io/BaGet/tools/sdk/) | [Samples](https://github.com/loic-sharma/BaGet/tree/master/samples) ## Getting started @@ -14,33 +14,78 @@ dotnet add package BaGet.Protocol ## Examples -### Downloading a package +### List Package Versions + +Find all versions of the `Newtonsoft.Json` package: ```csharp -using BaGet.Protocol; -using NuGet.Versioning; +NuGetClient client = new NuGetClient("https://api.nuget.org/v3/index.json"); + +IReadOnlyList> versions = await client.ListPackageVersionsAsync("Newtonsoft.Json"); -var client = new NuGetClient("https://api.nuget.org/v3/index.json"); +foreach (NuGetVersion version in versions) +{ + Console.WriteLine($"Found version: {version}"); +} +``` -var packageId = "Newtonsoft.Json"; -var packageVersion = new NuGetVersion("12.0.1"); +### Download a package -using (var packageStream = await client.GetPackageStreamAsync(packageId, packageVersion)) +```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 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 -// Searches for "json" packages, including prerelease packages. -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} total results"); -foreach (var searchResult in response.Data) +foreach (SearchResult searchResult in response.Data) { Console.WriteLine($"Found package {searchResult.Id} {searchResult.Version}"); }