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.
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.
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.
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).
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.
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}");
}
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()}");
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}");
}
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}");
}
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);
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);
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}");
}
Instale o pacote NuGet.Packaging
para interagir com os arquivos .nupkg
e .nuspec
arquivos de um fluxo:
dotnet add package NuGet.Packaging
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}");
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}");
}
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: