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
安装 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
安装 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 包的其他方法：
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈