SDK cliente de NuGet

  • Artigo

El SDK cliente de NuGet hace referencia a un grupo de paquetes NuGet:

  • NuGet.Indexing: biblioteca de indexación de NuGet para la funcionalidad de búsqueda cliente de Visual Studio.
  • NuGet.Commands: comandos completos comunes a los clientes NuGet de línea de comandos y GUI.
  • NuGet.Common: utilidades e interfaces comunes para todas las bibliotecas de NuGet.
  • NuGet.Configuration: implementación de las opciones de configuración de NuGet.
  • NuGet.Credentials: modelos de autenticación del cliente NuGet.
  • NuGet.DependencyResolver.Core: implementación del solucionador de dependencias PackageReference de NuGet.
  • NuGet.Frameworks: conocimientos de NuGet de las plataformas de destino.
  • NuGet.LibraryModel: tipos e interfaces de NuGet para comprender las dependencias.
  • NuGet.Localization: paquete de localización de NuGet.
  • NuGet.PackageManagement: funcionalidad de administración de paquetes NuGet para el flujo de instalación de Visual Studio.
  • NuGet.Packaging: proporciona un conjunto de API para interactuar con archivos .nupkg y .nuspec desde una secuencia. NuGet.Protocol depende de este paquete.
  • NuGet.ProjectModel: tipos principales e interfaces de NuGet para la restauración basada en PackageReference, como archivos de bloqueo, archivos de recursos y modelos de restauración internos.
  • NuGet.Protocol: proporciona un conjunto de API que interactúan con fuentes de NuGet HTTP y basadas en archivos.
  • NuGet.Resolver: resolución de dependencias de NuGet para proyectos basados en packages.config.
  • NuGet.Versioning: implementación de NuGet del control de versiones semántico.

Puede encontrar el código fuente de estos paquetes en el repositorio NuGet/NuGet.Client de GitHub.

Nota:

Para obtener documentación sobre el protocolo de servidor NuGet, consulte la API NuGet Server.

Directiva de soporte técnico

Todos los errores de seguridad deben notificarse al Centro de respuestas de seguridad de Microsoft (MSRC) en la página del informe de MSRC. Consulte también la directiva de seguridad en el repositorio NuGet.Client.

No garantizamos la estabilidad de la API, ya que la responsabilidad de nuestro equipo son las herramientas, no las bibliotecas. Consulte la documentación del SDK de NuGet en el repositorio NuGet.Client para obtener más información.

NuGet.Protocol

Instale el paquete NuGet.Protocol para interactuar con fuentes de paquetes NuGet HTTP y basadas en carpetas:

dotnet add package NuGet.Protocol

Puede encontrar el código fuente de estos ejemplos en el proyecto NuGet.Protocol.Samples en GitHub.

Sugerencia

Repository.Factory se define en el espacio de nombres NuGet.Protocol.Core.Types y GetCoreV3 es un método de extensión definido en el espacio de nombres NuGet.Protocol. Por tanto, deberá agregar instrucciones using para ambos espacios de nombres.

Enumeración de versiones de paquetes

Busque todas las versiones de Newtonsoft.Json mediante la API NuGet V3 Package Content:

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

Descarga de un paquete

Descargue Newtonsoft.Json v12.0.1 mediante la API NuGet V3 Package Content:

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

Obtención de metadatos de paquete

Obtenga los metadatos del paquete "Newtonsoft.Json" mediante la API NuGet V3 Package Metadata:

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

Búsqueda de paquetes

Busque paquetes "json" mediante la API NuGet V3 Search:

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

Inserción de un paquete

Inserte un paquete mediante la API NuGet V3 Push and 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);

Eliminación de un paquete

Elimine un paquete mediante la API NuGet V3 Push and Delete:

Nota:

Los servidores NuGet pueden interpretar una solicitud de eliminación de paquetes como una "eliminación permanente", "eliminación temporal" o "anulación de la lista". Por ejemplo, nuget.org interpreta la solicitud de eliminación de paquete como una "anulación de lista". Para más información sobre esta práctica, vea la directiva Eliminación de paquetes.

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

Trabajo con fuentes autenticadas

Use NuGet.Protocol para trabajar con fuentes autenticadas.

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 el paquete NuGet.Packaging para interactuar con archivos .nupkg y .nuspec desde una secuencia:

dotnet add package NuGet.Packaging

Creación de un paquete

Cree un paquete, establezca metadatos y agregue dependencias mediante NuGet.Packaging.

Importante

Se recomienda encarecidamente crear paquetes NuGet mediante las herramientas oficiales de NuGet y no usar esta API de bajo nivel. Hay una variedad de características importantes para un paquete bien formado y la versión más reciente de herramientas ayuda a incorporar estos procedimientos recomendados.

Para más información sobre la creación de paquetes NuGet, vea la introducción al flujo de trabajo de creación de paquetes y la documentación sobre las herramientas de paquetes oficiales (por ejemplo, el uso de la CLI de 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}");

Lectura de un paquete

Lea un paquete de una secuencia de archivos mediante 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}");
}

Documentación de terceros

Puede encontrar ejemplos y documentación sobre algunas de las API en la siguiente serie de blog de Dave Glick, publicada en 2016:

Nota:

Estas entradas de blog se escribieron poco después de que se publicara la versión 3.4.3 de los paquetes del SDK cliente de NuGet. Es posible que las versiones más recientes de los paquetes sean incompatibles con la información de las entradas de blog.

Martin Björkström ha publicado una entrada de blog de seguimiento de la serie de blogs de Dave Glick, donde presenta otro enfoque sobre el uso del SDK cliente de NuGet para instalar paquetes NuGet: