NuGet-Client SDK

Das NuGet-Client-SDK bezieht sich auf eine Gruppe von NuGet-Paketen:

• NuGet.Indexing – Die Indizierungsbibliothek von NuGet für die Clientsuchfunktion von Visual Studio.
• NuGet.Commands – Vollständige Befehle, die für Befehlszeilen- und GUI-NuGet-Clients verwendet werden.
• NuGet.Common – Allgemeine Hilfsprogramme und Schnittstellen für alle NuGet-Bibliotheken.
• NuGet.Configuration – Implementierung der Konfigurationseinstellungen von NuGet.
• NuGet.Credentials – Die Authentifizierungsmodelle des NuGet-Clients.
• NuGet.DependencyResolver.Core – Implementierung des PackageReference-Abhängigkeitslösers von NuGet.
• NuGet.Frameworks – NuGets Verständnis von Zielframeworks.
• NuGet.LibraryModel – Die Typen und Schnittstellen von NuGet zum Verständnis von Abhängigkeiten.
• NuGet.Localization – NuGet-Lokalisierungspaket.
• NuGet.PackageManagement – NuGet-Paketverwaltungsfunktionen für den Visual Studio-Installationsablauf.
• NuGet.Packaging – Stellt eine Reihe von APIs für die Interaktion mit .nupkg und .nuspec Dateien aus einem Datenstrom bereit. NuGet.Protocol hängt von diesem Paket ab.
• NuGet.ProjectModel – Die Kerntypen und Schnittstellen von NuGet für die auf PackageReference basierende Wiederherstellung, z. B. Sperrdateien, Ressourcendatei und interne Wiederherstellungsmodelle.
• NuGet.Protocol – Stellt eine Reihe von APIs bereit, die mit HTTP- und dateibasierten NuGet-Feeds interagieren.
• NuGet.Resolver – NuGets Abhängigkeitslöser für packages.config-basierte Projekte.
• NuGet.Versioning – NuGets Implementierung der semantischen Versionsverwaltung.

Den Quellcode für diese Pakete finden Sie im GitHub-Repository NuGet/NuGet.Client.

Hinweis

Dokumentation zum NuGet-Serverprotokoll finden Sie in der NuGet-Server-API.

Supportrichtlinie

Die neueste Version des NuGet Client SDK wird vollständig unterstützt und kann für Programmfehlerbehebungen, Updates und Erweiterungen verwendet werden.

Es wird empfohlen, die neuesten Versionen der NuGet Client SDK-Pakete zu verwenden und Ihr Projekt auf Abhängigkeiten von veralteten NuGet Client SDK-Paketen zu überprüfen.

Patchreleases

Gepatchte Versionen von NuGet Client SDK werden ausschließlich dann freigegeben, wenn kritische Bugs oder Sicherheitsbehebungen für eine Long-Term-Support-Version (LTS) von Visual Studio oder .NET SDK erforderlich sind.

Jegliche Sicherheitsfehler sollten dem Microsoft Security Response Center (MSRC) auf der Berichtsseite von MSRC gemeldet werden. Siehe auch die Sicherheitsrichtlinie im NuGet.Client-Repository.

Wir garantieren keine API-Stabilität, da der Verantwortungsbereich unseres Teams das Tooling, nicht aber die Bibliotheken umfasst. Weitere Informationen finden Sie in der NuGet SDK-Dokumentation im NuGet.Client-Repository.

Veraltetes Paket

Nicht mehr unterstützte NuGet Client SDK-Pakete, die nicht an eine LTS-Version von Visual Studio oder .NET gebunden sind, werden auf nuget.org veraltet sein.

Der Ansatz der NuGet-Paketwartung wird sich an den Richtlinien für die .NET-Paketwartung (Veraltetes Paket) ausrichten.

NuGet.Protocol

Installieren Sie das NuGet.Protocol Paket für die Interaktion mit HTTP- und ordnerbasierten NuGet-Paketfeeds:

dotnet add package NuGet.Protocol

Den Quellcode für diese Beispiele finden Sie im Projekt NuGet.Protocol.Samples auf GitHub.

Tipp

Repository.Factory wird im NuGet.Protocol.Core.Types Namespace definiert, und die GetCoreV3 Methode ist eine Erweiterungsmethode, die NuGet.Protocol im Namespace definiert ist. Daher müssen Sie using Anweisungen für beide Namespaces hinzufügen.

Abrufen von Paketversionen

Suchen Sie alle Versionen von Newtonsoft.Json mithilfe der NuGet V3-Paketinhalts-API:

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

Paket herunterladen

Laden Sie Newtonsoft.Json v12.0.1 mithilfe der NuGet V3-Paketinhalts-API herunter:

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

Paketmetadaten

Rufen Sie die Metadaten für das Paket Newtonsoft.Json mithilfe der NuGet V3-Paketmetadaten-API ab:

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

Suchen von Paketen

Suchen Sie mithilfe der NuGet V3-Such-API nach json-Paketen:

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

Pushen eines Pakets

Übertragen eines Pakets mithilfe der NuGet V3-Push- und Lösch-API:

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

Löschen eines Pakets

Löschen eines Pakets mithilfe der NuGet V3-Push- und Lösch-API:

Hinweis

NuGet-Server können eine Paketlöschanforderung als „endgültiges Löschen“, „vorläufiges Löschen“ oder „unlist“ interpretieren. Beispielsweise interpretiert nuget.org die Paketlöschanforderung als Unlist. Weitere Informationen zu dieser Vorgehensweise finden Sie in der Richtlinie zum Löschen von Paketen .

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

Arbeiten mit authentifizierten Feeds

Nutzen Sie NuGet.Protocol zum Arbeiten mit authentifizierten Feeds

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

Installieren Sie das NuGet.Packaging Paket für die Interaktion mit .nupkg und .nuspec Dateien aus einem Stream:

dotnet add package NuGet.Packaging

Erstellen eines Pakets

Erstellen Eines Pakets, Festlegen von Metadaten und Hinzufügen von Abhängigkeiten mithilfe von NuGet.Packaging.

Wichtig

Es wird dringend empfohlen, NuGet-Pakete mithilfe des offiziellen NuGet-Tools zu erstellen und diese API auf niedriger Ebene nicht zu verwenden. Es gibt eine Vielzahl von Merkmalen, die für ein wohlgeformtes Paket wichtig sind, und die neueste Version der Tools hilft bei der Integration dieser bewährten Methoden.

Weitere Informationen zum Erstellen von NuGet-Paketen finden Sie in der Übersicht über den Paketerstellungsworkflow und die Dokumentation für offizielle Packtools (z. B. mithilfe der dotnet CLI).

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

Lesen eines Pakets

Lesen eines Pakets aus einem Dateidatenstrom mithilfe von 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}");
}

Dokumentation von Drittanbietern

Beispiele und Dokumentationen für einige der API finden Sie in der folgenden Blogreihe von Dave Glick, veröffentlicht 2016:

• Erkunden der NuGet v3-Bibliotheken, Teil 1: Einführung und Konzepte
• Erkunden der NuGet v3-Bibliotheken, Teil 2: Suchen nach Paketen
• Erkunden der NuGet v3-Bibliotheken, Teil 3: Installieren von Paketen

Hinweis

Diese Blogbeiträge wurden kurz nach der 3.4.3-Version der NuGet-Client-SDK-Pakete veröffentlicht. Neuere Versionen der Pakete sind möglicherweise nicht mit den Informationen in den Blogbeiträgen kompatibel.

Martin Björkström hat einen Nachverfolgungsblogbeitrag zu Dave Glicks Blogreihe gemacht, in der er einen anderen Ansatz bei der Verwendung des NuGet Client SDK zum Installieren von NuGet-Paketen einführt:

• Erneutes Abrufen der NuGet v3-Bibliotheken