Поделиться через

Пакет SDK для клиента NuGet

  • Статья

Пакет SDK для клиента NuGet относится к группе пакетов NuGet:

  • NuGet.Indexing — Библиотека индексирования NuGet для функций поиска клиента Visual Studio.
  • NuGet.Commands — Выполнение команд, распространенных для клиентов NuGet в командной строке и графическом интерфейсе.
  • NuGet.Common — Общие служебные программы и интерфейсы для всех библиотек NuGet.
  • NuGet.Configuration — реализация параметров конфигурации NuGet.
  • NuGet.Credentials — Модели проверки подлинности клиента NuGet.
  • NuGet.DependencyResolver.Core — Реализация сопоставителя зависимостей ПакетаReference NuGet.
  • NuGet.Frameworks — понимание целевых платформ NuGet.
  • NuGet.LibraryModel — Типы и интерфейсы NuGet для понимания зависимостей.
  • NuGet.Localization — пакет локализации NuGet.
  • NuGet.PackageManagement — Функции управления пакетами NuGet для потока установки Visual Studio.
  • NuGet.Packaging — предоставляет набор API для взаимодействия и .nupkg.nuspec файлов из потока. NuGet.Protocol зависит от этого пакета.
  • NuGet.ProjectModel — Основные типы и интерфейсы NuGet для восстановления на основе PackageReference, таких как файлы блокировки, файлы ресурсов и внутренние модели восстановления.
  • NuGet.Protocol — предоставляет набор API-интерфейсов, взаимодействующих с ВЕБ-каналами NuGet на основе HTTP и файлов.
  • NuGet.Resolver — сопоставитель зависимостей NuGet для проектов на основе packages.config.
  • NuGet.Versioning — Реализация NuGet семантического управления версиями.

Исходный код для этих пакетов можно найти в репозитории NuGet/NuGet.Client GitHub.

Примечание.

Документацию по протоколу сервера NuGet см. в API NuGet Server.

Политика поддержки

Последняя версия пакета SDK для клиента NuGet полностью поддерживается и может использоваться для исправлений ошибок, обновлений и улучшений.

Рекомендуется использовать последние версии пакетов SDK для клиентов NuGet, а также проверить проект зависимостей на устаревших пакетах SDK для клиентов NuGet.

Выпуски исправлений

Исправленные версии пакета SDK для клиента NuGet будут выпущены исключительно в случае критических ошибок или исправлений безопасности, необходимых для долгосрочной поддержки (LTS) версии Visual Studio или пакета SDK для .NET.

Все ошибки безопасности должны сообщаться в Центр реагирования майкрософт (MSRC) на странице отчета MSRC. Кроме того, см. политику безопасности в репозитории NuGet.Client.

Мы не гарантируем стабильность API, так как ответственность нашей команды является инструментом, а не библиотеками. Дополнительные сведения см. в документации по пакету SDK NuGet.Client .

Отмена выпуска пакета

Пакеты sdk для клиента NuGet, не привязанные к версии LTS Visual Studio или .NET, будут устарели на nuget.org.

Подход к обслуживанию пакетов NuGet соответствует рекомендациям по обслуживанию пакетов .NET (нерекомендуемым).

NuGet.Protocol

NuGet.Protocol Установите пакет для взаимодействия с веб-каналами пакетов NuGet на основе HTTP и папок:

dotnet add package NuGet.Protocol

Исходный код для этих примеров можно найти в проекте NuGet.Protocol.Samples на сайте GitHub.

Совет

Repository.Factory определяется в NuGet.Protocol.Core.Types пространстве имен, а GetCoreV3 метод — это метод расширения, определенный NuGet.Protocol в пространстве имен. Поэтому необходимо добавить using инструкции для обоих пространств имен.

Вывод списка версий пакета

Найдите все версии Newtonsoft.Json с помощью API содержимого пакета NuGet версии 3:

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}");
}

Скачивание пакета

Скачайте Newtonsoft.Json версии 12.0.1 с помощью API содержимого пакета NuGet версии 3:

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()}");

Получение метаданных пакета

Получите метаданные для пакета Newtonsoft.Json с помощью API метаданных пакета NuGet версии 3:

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}");
}

Поиск пакетов

Выполните поиск пакетов json с помощью API поиска NuGet версии 3:

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}");
}

Отправка пакета

Отправка пакета с помощью API push-отправки и удаления NuGet версии 3:

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);

Удаление пакета

Удалите пакет с помощью API push-отправки и удаления NuGet версии 3:

Примечание.

Серверы NuGet могут интерпретировать запрос на удаление пакета как "жесткое удаление", "обратимое удаление" или "отменить список". Например, nuget.org интерпретирует запрос на удаление пакета как "unlist". Дополнительные сведения об этой практике см. в политике удаления пакетов .

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}");
}

Документация сторонних разработчиков

Примеры и документацию для некоторых API можно найти в следующей серии блогов Dave Glick, опубликованной в 2016 году:

Примечание.

Эти записи блога были написаны вскоре после выпуска пакета SDK для клиента NuGet версии 3.4.3 . Более новые версии пакетов могут быть несовместимы с информацией в записях блога.

Мартин Björkström сделал следующую запись блога в серии блогов Дэйв Glick, где он вводит другой подход к использованию пакета SDK для клиента NuGet для установки пакетов NuGet: