使用英语阅读

通过


NuGet 客户端 SDK

NuGet 客户端 SDK 是指一组 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 包的其他方法: