SDK cliente de NuGet

El SDK de 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 de 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 APIs para interactuar con los archivos .nupkg y .nuspec de 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 activos y modelos de restauración internos.
  • NuGet.Protocol - Proporciona un conjunto de API que interactúa con fuentes de NuGet basadas en archivos y HTTP.
  • NuGet.Resolver - Resolución de dependencias de NuGet para proyectos basados en packages.config.
  • NuGet.Versioning - Implementación de la versión semántica de NuGet.

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

Nota:

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

Directiva de soporte técnico

La versión más reciente del SDK de cliente nuGet es totalmente compatible y se puede confiar en para correcciones de errores, actualizaciones y mejoras.

La recomendación es usar las versiones más recientes de los paquetes del SDK de cliente de NuGet y examinar el proyecto para ver las dependencias de los paquetes de SDK de cliente nuGet en desuso.

Lanzamientos de parches

Las versiones revisadas del SDK de cliente de NuGet se publicarán exclusivamente cuando se requieran errores críticos o correcciones de seguridad para una versión de soporte técnico a largo plazo (LTS) de Visual Studio o el SDK de .NET.

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 es herramientas, no bibliotecas. Consulte la documentación del SDK de NuGet en el repositorio NuGet.Client para obtener más información.

Deprecación del paquete

Los paquetes de SDK de cliente NuGet no compatibles que no están vinculados a una versión LTS de Visual Studio o .NET quedarán en desuso en nuget.org.

El enfoque de mantenimiento de paquetes de NuGet se alineará con la orientación de mantenimiento de paquetes de .NET (obsolescencia).

NuGet.Protocol

Instale el NuGet.Protocol paquete para interactuar con fuentes de paquetes NuGet basadas en HTTP y 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 NuGet.Protocol.Core.Types espacio de nombres y el GetCoreV3 método es un método de extensión definido en el NuGet.Protocol espacio de nombres. Por lo tanto, deberá agregar using declaraciones para ambos espacios de nombres.

Enumerar las versiones del paquete

Busque todas las versiones de Newtonsoft.Json mediante la API de contenido del paquete V3 de NuGet:

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

Descargar un paquete

Descargue Newtonsoft.Json v12.0.1 mediante la API de contenido del paquete V3 de NuGet:

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 del paquete

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

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 NuGet V3 Search API:

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 de inserción y eliminación de 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);

Eliminación de un paquete

Elimine un paquete mediante la API de envío y eliminación de NuGet V3:

Nota:

Los servidores NuGet pueden interpretar una solicitud de eliminación de paquetes como una "eliminación fuerte", "eliminación suave" o "anulación de la lista". Por ejemplo, nuget.org interpreta la solicitud de eliminación del paquete como una "anulación de lista". Para obtener más información sobre esta práctica, consulte la directiva Eliminar 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);

Trabajar 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 .nupkg archivos y .nuspec desde un flujo.

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

Leer un paquete

Lee un paquete de un flujo 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 de cliente nuGet. Las versiones más recientes de los paquetes pueden ser incompatibles con la información de las entradas de blog.

Martin Björkström hizo una entrada de blog de seguimiento en la serie de blog de Dave Glick, donde presenta un enfoque diferente sobre el uso del SDK de cliente de NuGet para instalar paquetes NuGet:

  • Last updated on