NuGet 客户端 SDK
NuGet 客户端 SDK 是指一组 NuGet 包:
NuGet.Indexing
- 适用于 Visual Studio 客户端搜索功能的 NuGet 索引库。NuGet.Commands
- 完整的命令行和 GUI NuGet 客户端通用命令。NuGet.Common
- 所有 NuGet 库的通用实用工具和接口。NuGet.Configuration
- NuGet 的配置设置实现。NuGet.Credentials
- NuGet 的客户端身份验证模型。NuGet.DependencyResolver.Core
- NuGet 的 PackageReference 依赖项解析程序实现。NuGet.Frameworks
- NuGet 的目标框架理解。NuGet.LibraryModel
- NuGet 用于理解依赖项的类型和接口。NuGet.Localization
- NuGet 本地化包。NuGet.PackageManagement
- 适用于 Visual Studio 安装流的 NuGet 包管理功能。NuGet.Packaging
- 提供了一组用于与流中的.nupkg
和.nuspec
文件进行交互的 API。NuGet.Protocol
依赖于此包。NuGet.ProjectModel
- 适用于基于 PackageReference 的还原的 NuGet 核心类型和接口,例如锁定的文件、资产文件和内部还原模型。NuGet.Protocol
- 提供了一组用于与 HTTP 和基于文件的 NuGet 源进行交互的 API。NuGet.Resolver
- 适用于基于 packages.config 的项目的NuGet 依赖项解析程序。NuGet.Versioning
- NuGet 的语义化版本控制实现。
可在 NuGet/NuGet.Client GitHub 存储库中找到这些包的源代码。
备注
有关 NuGet 服务器协议的文档,请参阅 NuGet 服务器 API。
NuGet 客户端 SDK 的最新版本完全受支持,可以依赖于缺陷修复、更新以及增强功能。
建议使用最新版本的 NuGet 客户端 SDK 包并检查项目是否依赖于已弃用的 NuGet 客户端 SDK 包。
当 Visual Studio 或 .NET SDK 的长期支持 (LTS) 版本需要关键 bug 或安全修补程序时,将专门发布 NuGet 客户端 SDK 的修补版本。
所有安全 bug 都会在 Microsoft 安全响应中心(MSRC) 的 MSRC 报告页面。 另请参阅 NuGet.Client 存储库中的安全策略。
我们团队的责任是提供工具,而提供库并不是我们的责任,因此我们无法保证 API 稳定性。 有关详细信息,请参阅 NuGet.Client 存储库中的 NuGet SDK 文档。
未绑定到 Visual Studio 或 .NET 的 LTS 版本的不支持的 NuGet 客户端 SDK 包将在 nuget.org 上弃用。
NuGet 的包维护方法将与 .NET 包维护(弃用)指导保持一致。
安装 NuGet.Protocol
包以便与 HTTP 以及基于文件夹的 NuGet 包源进行交互:
dotnet add package NuGet.Protocol
可在 GitHub 上的 NuGet.Protocol.Samples 项目中找到这些示例的源代码。
提示
Repository.Factory
是在 NuGet.Protocol.Core.Types
命名空间中定义,而 GetCoreV3
方法则是在 NuGet.Protocol
命名空间中定义的扩展方法。 因此,需为这两个命名空间添加 using
语句。
使用 NuGet V3 包内容 API 查找 Newtonsoft.Json 的所有版本:
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceCacheContext cache = new SourceCacheContext();
SourceRepository repository = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
FindPackageByIdResource resource = await repository.GetResourceAsync<FindPackageByIdResource>();
IEnumerable<NuGetVersion> versions = await resource.GetAllVersionsAsync(
"Newtonsoft.Json",
cache,
logger,
cancellationToken);
foreach (NuGetVersion version in versions)
{
Console.WriteLine($"Found version {version}");
}
使用 NuGet V3 包内容 API 下载 Newtonsoft.Json v12.0.1:
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceCacheContext cache = new SourceCacheContext();
SourceRepository repository = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
FindPackageByIdResource resource = await repository.GetResourceAsync<FindPackageByIdResource>();
string packageId = "Newtonsoft.Json";
NuGetVersion packageVersion = new NuGetVersion("12.0.1");
using MemoryStream packageStream = new MemoryStream();
await resource.CopyNupkgToStreamAsync(
packageId,
packageVersion,
packageStream,
cache,
logger,
cancellationToken);
Console.WriteLine($"Downloaded package {packageId} {packageVersion}");
using PackageArchiveReader packageReader = new PackageArchiveReader(packageStream);
NuspecReader nuspecReader = await packageReader.GetNuspecReaderAsync(cancellationToken);
Console.WriteLine($"Tags: {nuspecReader.GetTags()}");
Console.WriteLine($"Description: {nuspecReader.GetDescription()}");
使用 NuGet V3 包元数据 API 获取“Newtonsoft.Json”包的元数据:
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceCacheContext cache = new SourceCacheContext();
SourceRepository repository = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
PackageMetadataResource resource = await repository.GetResourceAsync<PackageMetadataResource>();
IEnumerable<IPackageSearchMetadata> packages = await resource.GetMetadataAsync(
"Newtonsoft.Json",
includePrerelease: true,
includeUnlisted: false,
cache,
logger,
cancellationToken);
foreach (IPackageSearchMetadata package in packages)
{
Console.WriteLine($"Version: {package.Identity.Version}");
Console.WriteLine($"Listed: {package.IsListed}");
Console.WriteLine($"Tags: {package.Tags}");
Console.WriteLine($"Description: {package.Description}");
}
使用 NuGet V3 搜索 API 搜索“json”包:
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceRepository repository = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
PackageSearchResource resource = await repository.GetResourceAsync<PackageSearchResource>();
SearchFilter searchFilter = new SearchFilter(includePrerelease: true);
IEnumerable<IPackageSearchMetadata> results = await resource.SearchAsync(
"json",
searchFilter,
skip: 0,
take: 20,
logger,
cancellationToken);
foreach (IPackageSearchMetadata result in results)
{
Console.WriteLine($"Found package {result.Identity.Id} {result.Identity.Version}");
}
使用 NuGet V3 推送和删除 API 来推送包:
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceCacheContext cache = new SourceCacheContext();
SourceRepository repository = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
PackageUpdateResource resource = await repository.GetResourceAsync<PackageUpdateResource>();
string apiKey = "my-api-key";
await resource.Push(
"MyPackage.nupkg",
symbolSource: null,
timeoutInSecond: 5 * 60,
disableBuffering: false,
getApiKey: packageSource => apiKey,
getSymbolApiKey: packageSource => null,
noServiceEndpoint: false,
skipDuplicate: false,
symbolPackageUpdateResource: null,
logger);
使用 NuGet V3 推送和删除 API 来删除包:
备注
NuGet 服务器可随意将包删除请求解释为“硬删除”、“软删除”或“取消列出”。 例如,nuget.org 会将包删除请求解释为“取消列出”。 有关此实践的详细信息,请参阅删除包策略。
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceCacheContext cache = new SourceCacheContext();
SourceRepository repository = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
PackageUpdateResource resource = await repository.GetResourceAsync<PackageUpdateResource>();
string apiKey = "my-api-key";
await resource.Delete(
"MyPackage",
"1.0.0-beta",
getApiKey: packageSource => apiKey,
confirm: packageSource => true,
noServiceEndpoint: false,
logger);
使用 NuGet.Protocol
以使用已经过身份验证的源。
ILogger logger = NullLogger.Instance;
CancellationToken cancellationToken = CancellationToken.None;
SourceCacheContext cache = new SourceCacheContext();
var sourceUri = "https://contoso.privatefeed/v3/index.json";
var packageSource = new PackageSource(sourceUri)
{
Credentials = new PackageSourceCredential(
source: sourceUri,
username: "myUsername",
passwordText: "myVerySecretPassword",
isPasswordClearText: true,
validAuthenticationTypesText: null)
};
// If the `SourceRepository` is created with a `PackageSource`, the rest of APIs will consume the credentials attached to `PackageSource.Credentials`.
SourceRepository repository = Repository.Factory.GetCoreV3(packageSource);
PackageMetadataResource resource = await repository.GetResourceAsync<PackageMetadataResource>();
IEnumerable<IPackageSearchMetadata> packages = await resource.GetMetadataAsync(
"MyPackage",
includePrerelease: true,
includeUnlisted: false,
cache,
logger,
cancellationToken);
foreach (IPackageSearchMetadata package in packages)
{
Console.WriteLine($"Version: {package.Identity.Version}");
Console.WriteLine($"Listed: {package.IsListed}");
Console.WriteLine($"Tags: {package.Tags}");
Console.WriteLine($"Description: {package.Description}");
}
安装 NuGet.Packaging
包以便与流中的 .nupkg
和 .nuspec
文件进行交互:
dotnet add package NuGet.Packaging
使用 NuGet.Packaging
来创建包、设置元数据和添加依赖项。
重要
强烈建议使用官方 NuGet 工具来创建 NuGet 包,而不使用此低级 API。 对于格式正确的包,有多种特征对其十分重要,而最新版本的工具有助于整合这些最佳实践。
有关创建 NuGet 包的详细信息,请参阅包创建工作流的概述以及官方包工具的相关文档(例如,使用 dotnet CLI)。
PackageBuilder builder = new PackageBuilder();
builder.Id = "MyPackage";
builder.Version = new NuGetVersion("1.0.0-beta");
builder.Description = "My package created from the API.";
builder.Authors.Add("Sample author");
builder.DependencyGroups.Add(new PackageDependencyGroup(
targetFramework: NuGetFramework.Parse("netstandard1.4"),
packages: new[]
{
new PackageDependency("Newtonsoft.Json", VersionRange.Parse("10.0.1"))
}));
using FileStream outputStream = new FileStream("MyPackage.nupkg", FileMode.Create);
builder.Save(outputStream);
Console.WriteLine($"Saved a package to {outputStream.Name}");
使用 NuGet.Packaging
以从文件流读取包。
using FileStream inputStream = new FileStream("MyPackage.nupkg", FileMode.Open);
using PackageArchiveReader reader = new PackageArchiveReader(inputStream);
NuspecReader nuspec = reader.NuspecReader;
Console.WriteLine($"ID: {nuspec.GetId()}");
Console.WriteLine($"Version: {nuspec.GetVersion()}");
Console.WriteLine($"Description: {nuspec.GetDescription()}");
Console.WriteLine($"Authors: {nuspec.GetAuthors()}");
Console.WriteLine("Dependencies:");
foreach (var dependencyGroup in nuspec.GetDependencyGroups())
{
Console.WriteLine($" - {dependencyGroup.TargetFramework.GetShortFolderName()}");
foreach (var dependency in dependencyGroup.Packages)
{
Console.WriteLine($" > {dependency.Id} {dependency.VersionRange}");
}
}
Console.WriteLine("Files:");
foreach (var file in reader.GetFiles())
{
Console.WriteLine($" - {file}");
}
可在 2016 年发布的 Dave Glick 的以下博客系列文章中找到部分 API 的示例和文档:
备注
这些博客文章是在 3.4.3 版本的 NuGet 客户端 SDK 包发布后不久编写的。 较新版本的包可能与博客文章中描述的信息不兼容。
Martin Björkström 已发布针对 Dave Glick 博客系列文章的后续博客文章,其中介绍了使用 NuGet 客户端 SDK 来安装 NuGet 包的其他方法: