Kit SDK du client NuGet

  • Article

Le Kit de développement logiciel (SDK) client NuGet fait référence à un groupe de packages NuGet :

  • NuGet.Indexing - Bibliothèque d’indexation de NuGet pour la fonctionnalité de recherche du client Visual Studio.
  • NuGet.Commands - Commandes complètes communes aux clients NuGet de ligne de commande et d’interface utilisateur graphique.
  • NuGet.Common - Utilitaires et interfaces courants pour toutes les bibliothèques NuGet.
  • NuGet.Configuration - Implémentation des paramètres de configuration de NuGet.
  • NuGet.Credentials - Modèles d’authentification du client NuGet.
  • NuGet.DependencyResolver.Core - Implémentation du programme de résolution de dépendances PackageReference de NuGet.
  • NuGet.Frameworks - Compréhension de NuGet des versions cibles de .Net Framework.
  • NuGet.LibraryModel - Types et interfaces de NuGet pour la compréhension des dépendances.
  • NuGet.Localization - Package de localisation NuGet.
  • NuGet.PackageManagement - Fonctionnalité Package Management de NuGet pour le flux d’installation de Visual Studio.
  • NuGet.Packaging- Fournit un ensemble d’API permettant d’interagir avec les fichiers .nupkg et .nuspec à partir d’un flux. NuGet.Protocol dépend de ce package.
  • NuGet.ProjectModel - Types et interfaces principaux de NuGet pour la restauration basée sur PackageReference, tels que les fichiers de verrouillage, les fichiers de ressources et les modèles de restauration interne.
  • NuGet.Protocol - Fournit un ensemble d’API interagissent avec les flux NuGet HTTP et basés sur des fichiers.
  • NuGet.Resolver - Programme de résolution des dépendances de NuGet pour les projets basés sur packages.config.
  • NuGet.Versioning - Implémentation de la Gestion sémantique de version par NuGet.

Vous trouverez le code source de ces packages dans le référentiel GitHub NuGet/NuGet.Client.

Remarque

Pour obtenir de la documentation sur le protocole du serveur NuGet, reportez-vous à l’API serveur NuGet.

Politique de support

Tous les bogues de sécurité doivent être signalés au Centre de réponse aux problèmes de sécurité Microsoft (MSRC) sur la page de rapport de MSRC. Consultez également la stratégie de sécurité dans le référentiel NuGet.Client.

Nous ne garantissons pas la stabilité des API, car la responsabilité de notre équipe est l’outil, et non les bibliothèques. Pour plus d’informations, consultez la documentation du Kit de développement logiciel (SDK) NuGet dans le référentiel NuGet.Client.

NuGet.Protocol

Installez le package NuGet.Protocol pour interagir avec les flux de package NuGet HTTP et basés sur des dossiers :

dotnet add package NuGet.Protocol

Vous trouverez le code source de ces exemples sur le projet NuGet.Protocol.Samples sur GitHub.

Conseil

Repository.Factory est défini dans l’espace de noms NuGet.Protocol.Core.Types et la méthode GetCoreV3 est une méthode d’extension définie dans l’espace de noms NuGet.Protocol. Par conséquent, vous devez ajouter des instructions using pour les deux espaces de noms.

Répertorier des versions de packages

Recherchez toutes les versions de Newtonsoft.Json à l’aide de l’API de contenu du package 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}");
}

Télécharger un package

Téléchargez Newtonsoft.Json v12.0.1 à l’aide de l’API de contenu du package 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()}");

Obtenir les métadonnées de package

Obtenez les métadonnées du package « Newtonsoft.Json » à l’aide de l’API de métadonnées de package 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}");
}

Rechercher des packages

Recherchez des packages « json » à l’aide de l’API de recherche 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}");
}

Envoyer un package

Envoyez (push) un package à l’aide de l’API Envoyer et supprimer 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);

Supprimer un package

Supprimez un package à l’aide de l’API Envoyer et supprimer de NuGet V3 :

Remarque

Les serveurs NuGet sont libres d’interpréter une demande de suppression de package comme « suppression définitive », « suppression réversible » ou « retrait de la liste ». Par exemple, nuget.org interprète la demande de suppression de package en tant que « retrait de la liste ». Pour plus d’informations sur cette pratique, consultez la stratégie Suppression de packages.

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

Utiliser des flux authentifiés

Utilisez des flux authentifiés à l’aide de NuGet.Protocol.

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

Installez le package NuGet.Packaging pour interagir avec des fichiers .nupkg et .nuspec à partir d’un flux :

dotnet add package NuGet.Packaging

Créer un package

Créez un package, définissez des métadonnées et ajoutez des dépendances à l’aide de NuGet.Packaging.

Important

Il est fortement recommandé de créer des packages NuGet à l’aide des outils NuGet officiels et de ne pas utiliser cette API de bas niveau. Il existe diverses caractéristiques importantes pour un package bien formé et la dernière version des outils permet d’incorporer ces meilleures pratiques.

Pour plus d’informations sur la création de packages NuGet, consultez la vue d’ensemble du flux de travail de création de package et la documentation relative aux outils de pack officiels (par exemple, à l’aide de l’interface 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}");

Lire un package

Lire un package à partir d’un flux de fichiers à l’aide de 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}");
}

Documentation de tiers

Vous trouverez des exemples et de la documentation pour certaines des API dans la série de blogs suivante de Dave Glick, publié en 2016 :

Remarque

Ces billets de blog ont été écrits peu après la publication de la version 3.4.3 des packages du Kit de développement logiciel (SDK) client NuGet. Les versions plus récentes des packages peuvent être incompatibles avec les informations contenues dans les billets de blog.

Martin Björkström a créé un billet de blog de suivi sur la série de blogs de Dave Glick où il présente une approche différente sur l’utilisation du Kit de développement logiciel (SDK) client NuGet pour installer des packages NuGet :