SDK do cliente NuGet

O SDK do Cliente NuGet refere-se a um grupo de pacotes NuGet:

  • NuGet.Indexing – biblioteca de indexação do NuGet para a funcionalidade de pesquisa de cliente do Visual Studio.
  • NuGet.Commands – Comandos completos comuns aos clientes NuGet de linha de comando e GUI.
  • NuGet.Common – Utilitários e interfaces comuns para todas as bibliotecas Do NuGet.
  • NuGet.Configuration – Implementação das configurações do NuGet.
  • NuGet.Credentials – Modelos de autenticação do cliente NuGet.
  • NuGet.DependencyResolver.Core – Implementação do resolvedor de dependência PackageReference do NuGet.
  • NuGet.Frameworks – Compreensão do NuGet sobre estruturas de destino.
  • NuGet.LibraryModel – Tipos e interfaces do NuGet para entender as dependências.
  • NuGet.Localization - Pacote de localização do NuGet.
  • NuGet.PackageManagement – Funcionalidade de Gerenciamento de Pacotes NuGet para o fluxo de instalação do Visual Studio.
  • NuGet.Packaging - Fornece um conjunto de APIs para interagir com arquivos .nupkg e .nuspec a partir de um fluxo. NuGet.Protocol depende desse pacote.
  • NuGet.ProjectModel - Os principais tipos e interfaces do NuGet para restauração baseada em PackageReference, como arquivos de bloqueio, arquivos de ativos e modelos de restauração interna.
  • NuGet.Protocol - Fornece um conjunto de APIs para interagir com feeds NuGet baseados em HTTP e em arquivos.
  • NuGet.Resolver – Resolvedor de dependência do NuGet para projetos baseados em packages.config.
  • NuGet.Versioning – Implementação do Versionamento Semântico no NuGet.

Você pode encontrar o código-fonte desses pacotes no repositório GitHub NuGet/NuGet.Client .

Observação

Para obter documentação sobre o protocolo do servidor NuGet, consulte a API do Servidor NuGet.

Política de suporte

A versão mais recente do SDK do Cliente NuGet é totalmente suportada e pode ser confiável para correções de bugs, atualizações e aprimoramentos.

A recomendação é usar as versões mais recentes dos pacotes do SDK do Cliente NuGet e examinar seu projeto quanto a dependências em pacotes preteridos do SDK do Cliente NuGet.

Versões de patch

As versões corrigidas do SDK do Cliente NuGet serão lançadas exclusivamente quando bugs críticos ou correções de segurança forem necessárias para uma versão LTS (suporte de longo prazo) do Visual Studio ou do SDK do .NET.

Todos os bugs de segurança devem ser relatados ao MSRC (Centro de Resposta de Segurança da Microsoft) na página de relatório do MSRC. Além disso, consulte a política de segurança no repositório NuGet.Client.

Não garantimos a estabilidade da API, pois a responsabilidade da nossa equipe é de ferramentas, não de bibliotecas. Consulte a documentação do SDK do NuGet no repositório NuGet.Client para obter mais informações.

Descontinuação de Pacote

Pacotes de SDK de cliente NuGet sem suporte que não estão vinculados a uma versão LTS do Visual Studio ou do .NET serão preteridos em nuget.org.

A abordagem de manutenção de pacote do NuGet se alinhará às diretrizes de Manutenção de Pacote do .NET (depreciação).

NuGet.Protocol

Instale o pacote NuGet.Protocol para interagir com pacotes NuGet baseados em feeds HTTP e pastas.

dotnet add package NuGet.Protocol

Você pode encontrar o código-fonte para esses exemplos no projeto NuGet.Protocol.Samples no GitHub.

Dica

Repository.Factory é definido no NuGet.Protocol.Core.Types namespace e o GetCoreV3 método é um método de extensão definido no NuGet.Protocol namespace. Portanto, você precisará adicionar using declarações para ambos os namespaces.

Listar versões do pacote

Encontre todas as versões do Newtonsoft.Json usando a API de Conteúdo do Pacote NuGet V3:

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

Baixar um pacote

Baixe Newtonsoft.Json v12.0.1 usando a API de Conteúdo do Pacote NuGet V3:

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

Obter metadados do pacote

Obtenha os metadados do pacote "Newtonsoft.Json" usando a API de Metadados do Pacote NuGet V3:

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

Pesquisar pacotes

Pesquise pacotes "json" usando a API de Pesquisa do NuGet V3:

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

Realizar um push de um pacote

Envie um pacote usando a API de Push e Exclusão do NuGet V3:

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

Excluir um pacote

Exclua um pacote usando a API de Empurrar e Excluir do NuGet V3:

Observação

Os servidores NuGet têm liberdade para interpretar uma solicitação de exclusão de pacote como uma "exclusão irreversível", "exclusão temporária" ou "deslistar". Por exemplo, nuget.org interpreta a solicitação de exclusão de pacote como uma "unlist". Para obter mais informações sobre essa prática, consulte a política Excluir Pacotes .

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

Trabalhar com feeds autenticados

Use NuGet.Protocol para trabalhar com feeds autenticados.

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

Instale o pacote NuGet.Packaging para interagir com os arquivos .nupkg e .nuspec de um fluxo.

dotnet add package NuGet.Packaging

Criar um pacote

Crie um pacote, defina metadados e adicione dependências usando NuGet.Packaging.

Importante

É altamente recomendável que os pacotes NuGet sejam criados usando as ferramentas oficiais do NuGet e não usem essa API de baixo nível. Há uma variedade de características importantes para um pacote bem formado e a versão mais recente das ferramentas ajuda a incorporar essas práticas recomendadas.

Para obter mais informações sobre como criar pacotes NuGet, consulte a visão geral do fluxo de trabalho de criação de pacote e a documentação para ferramentas oficiais do pacote (por exemplo, usando a CLI do dotnet).

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

Analisar um pacote

Ler um pacote de um fluxo de arquivos usando 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}");
}

Documentação de terceiros

Você pode encontrar exemplos e documentação para algumas das API na seguinte série de blogs de Dave Glick, publicada em 2016:

Observação

Essas postagens de blog foram escritas logo após a versão 3.4.3 dos pacotes do SDK do cliente NuGet serem lançadas. As versões mais recentes dos pacotes podem ser incompatíveis com as informações nas postagens no blog.

Martin Björkström fez uma postagem de acompanhamento na série de blogs de Dave Glick, onde apresenta uma abordagem alternativa para usar o SDK do Cliente NuGet para instalar pacotes NuGet:

  • Last updated on