SDK do cliente NuGet

O SDK do Cliente do 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 a 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 de definições de configuração do NuGet.
• NuGet.Credentials - Modelos de autenticação do cliente do NuGet.
• NuGet.DependencyResolver.Core - Implementação do resolvedor de dependência PackageReference do NuGet.
• NuGet.Frameworks - Entendimento do NuGet sobre estruturas de destino.
• NuGet.LibraryModel - Tipos e interfaces do NuGet para entendimento de dependências.
• NuGet.Localization - Pacote de localização do NuGet.
• NuGet.PackageManagement - Funcionalidade de gerenciamento de pacotes do NuGet para fluxo de instalação do Visual Studio.
• NuGet.Packaging - Fornece um conjunto de APIs para interagir com .nupkg e arquivos .nuspec de um fluxo. NuGet.Protocol depende deste pacote.
• NuGet.ProjectModel - Tipos e interfaces principais 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 que interagem com feeds HTTP e NuGet baseados em arquivo.
• NuGet.Resolver - Resolvedor de dependências do NuGet para projetos baseados em packages.config.
• NuGet.Versioning - Implementação de versionamento semântico do 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 do NuGet.

Diretiva de suporte

A versão mais recente do SDK do cliente NuGet é totalmente compatível e pode ser usada 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 verificar se seu projeto tem dependências de pacotes do SDK do NuGet cliente que foram preteridos.

Lançamentos de patches

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

Todos os bugs de segurança devem ser relatados ao MSRC (Microsoft Security Response Center) na Página de relatórios 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 de nossa equipe é sobre ferramentas, não sobre bibliotecas. Consulte a documentação do SDK do NuGet no repositório NuGet.Client para obter mais informações.

Preterimento de pacote

Pacotes do SDK do cliente NuGet que não têm mais suporte e 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 pacotes do NuGet será alinhada com a orientação de Manutenção de Pacotes do .NET (preterimento).

NuGet.Protocol

Instale o pacote NuGet.Protocol para interagir com feeds de pacotes NuGet HTTP e baseados em pasta:

dotnet add package NuGet.Protocol

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

Dica

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

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

Fazer download de um pacote

Faça download do 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 de pacote

Obtenha os metadados para o 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

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

Efetuar push de um pacote

Envie um pacote por push usando NuGet V3 Push e a API Delete:

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 por push usando NuGet V3 Push e a API Delete:

Observação

Os servidores do NuGet são livres para interpretar uma solicitação de exclusão de pacote como uma "exclusão rígida", "exclusão flexível" ou "retirada da lista". Por exemplo, nuget.org interpreta a solicitação de exclusão de pacote como um "retirada da lista". 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 arquivos 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 usando essa API de baixo nível. Há uma variedade de características importantes para um pacote bem formado e a última versão 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 pacotes e a documentação das ferramentas oficiais de pacotes (por exemplo, usando a CLI 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}");

Ler um pacote

Leia 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 APIs na seguinte série de blogs de Dave Glick, publicados em 2016:

• Explorar as bibliotecas do NuGet v3, Parte 1: Introdução e conceitos
• Explorar as bibliotecas do NuGet v3, Parte 2: Procurando pacotes
• Explorar as bibliotecas do NuGet v3, Parte 3: Instalando pacotes

Observação

Essas postagens no blog foram escritas logo após o lançamento da versão 3.4.3 dos pacotes do SDK do cliente do NuGet. 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 no blog para a série de blogs de Dave Glick, na qual ele apresenta uma abordagem diferente sobre o uso do SDK do cliente do NuGet para instalar pacotes NuGet:

• Revisitando as bibliotecas do NuGet v3