Udostępnij za pośrednictwem

Zestaw SDK klienta programu NuGet

  • Artykuł

Zestaw SDK klienta NuGet odwołuje się do grupy pakietów NuGet:

  • NuGet.Indexing — Biblioteka indeksowania NuGet dla funkcji wyszukiwania klienta programu Visual Studio.
  • NuGet.Commands - Ukończ polecenia wspólne dla klientów NuGet wiersza polecenia i graficznego interfejsu użytkownika.
  • NuGet.Common — Typowe narzędzia i interfejsy dla wszystkich bibliotek NuGet.
  • NuGet.Configuration — Implementacja ustawień konfiguracji narzędzia NuGet.
  • NuGet.Credentials - Modele uwierzytelniania klienta NuGet.
  • NuGet.DependencyResolver.Core — Implementacja modułu rozpoznawania zależności PackageReference narzędzia NuGet.
  • NuGet.Frameworks — Znajomość platform docelowych w narzędziu NuGet.
  • NuGet.LibraryModel - Typy i interfejsy NuGet do zrozumienia zależności.
  • NuGet.Localization - Pakiet lokalizacji NuGet.
  • NuGet.PackageManagement — Funkcje zarządzania pakietami NuGet dla przepływu instalacji programu Visual Studio.
  • NuGet.Packaging — Udostępnia zestaw interfejsów API do interakcji z plikami .nupkg i .nuspec ze strumienia. NuGet.Protocol zależy od tego pakietu.
  • NuGet.ProjectModel — podstawowe typy i interfejsy NuGet dla przywracania opartego na elemencie PackageReference, takie jak pliki blokady, pliki zasobów i wewnętrzne modele przywracania.
  • NuGet.Protocol — Udostępnia zestaw interfejsów API współdziała z kanałami informacyjnymi NuGet opartymi na protokole HTTP i plikach.
  • NuGet.Resolver - Narzędzie rozpoznawania zależności NuGet dla projektów opartych na plikach packages.config.
  • NuGet.Versioning — Implementacja semantycznego przechowywania wersji programu NuGet.

Kod źródłowy tych pakietów można znaleźć w repozytorium GitHub NuGet/NuGet.Client .

Uwaga

Aby uzyskać dokumentację dotyczącą protokołu serwera NuGet, zapoznaj się z interfejsem API serwera NuGet.

Zasady pomocy technicznej

Najnowsza wersja zestawu SDK klienta NuGet jest w pełni obsługiwana i może być oparta na poprawkach usterek, aktualizacjach i ulepszeniach.

Zaleceniem jest użycie najnowszych wersji pakietów zestawu SDK klienta NuGet oraz sprawdzenie projektu pod kątem zależności od przestarzałych pakietów zestawu SDK klienta NuGet.

Wydania poprawek

Poprawkowe wersje zestawu NUGet Client SDK zostaną wydane wyłącznie wtedy, gdy krytyczne usterki lub poprawki zabezpieczeń są wymagane dla długoterminowej wersji programu Visual Studio lub zestawu SDK platformy .NET.

Wszystkie usterki zabezpieczeń powinny być zgłaszane do Centrum zabezpieczeń firmy Microsoft (MSRC) na stronie raportu MSRC. Zobacz również zasady zabezpieczeń w repozytorium NuGet.Client.

Nie gwarantujemy stabilności interfejsu API, ponieważ odpowiedzialność naszego zespołu to narzędzia, a nie biblioteki. Aby uzyskać więcej informacji, zobacz dokumentację zestawu NuGet SDK w repozytorium NuGet.Client.

Wycofanie pakietu

Pakiety zestawu SDK klienta NuGet, które nie są powiązane z wersją LTS programu Visual Studio lub platformy .NET, zostaną wycofane w nuget.org.

Podejście do konserwacji pakietów NuGet będzie zgodne ze wskazówkami dotyczącymi konserwacji pakietów platformy .NET (wycofywania).

NuGet.Protocol

Zainstaluj pakiet w NuGet.Protocol celu interakcji z kanałami informacyjnymi pakietów NuGet opartymi na protokole HTTP i folderach:

dotnet add package NuGet.Protocol

Kod źródłowy tych przykładów można znaleźć w projekcie NuGet.Protocol.Samples w witrynie GitHub.

Napiwek

Repository.Factory element jest zdefiniowany w NuGet.Protocol.Core.Types przestrzeni nazw, a GetCoreV3 metoda jest metodą rozszerzenia zdefiniowaną w NuGet.Protocol przestrzeni nazw. W związku z tym należy dodać using instrukcje dla obu przestrzeni nazw.

Wyświetlanie listy wersji pakietów

Znajdź wszystkie wersje pliku Newtonsoft.Json przy użyciu interfejsu API zawartości pakietu 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}");
}

Pobieranie pakietu

Pobierz plik Newtonsoft.Json v12.0.1 przy użyciu interfejsu API zawartości pakietu 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()}");

Pobieranie metadanych pakietu

Pobierz metadane pakietu "Newtonsoft.Json" przy użyciu interfejsu API metadanych pakietu 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}");
}

Wyszukaj pakiety

Wyszukaj pakiety "json" przy użyciu interfejsu API wyszukiwania NuGet w wersji 3:

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

Wypychanie pakietu

Wypychanie pakietu przy użyciu interfejsu API wypychania i usuwania nuGet w wersji 3:

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

Usuwanie pakietu

Usuń pakiet przy użyciu interfejsu API wypychania i usuwania nuGet w wersji 3:

Uwaga

Serwery NuGet mogą interpretować żądanie usuwania pakietu jako "usuwanie twarde", "usuwanie nietrwałe" lub "unlist". Na przykład nuget.org interpretuje żądanie usuwania pakietu jako "unlist". Aby uzyskać więcej informacji na temat tej praktyki, zobacz zasady Usuwanie pakietów .

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

Praca z uwierzytelnionymi kanałami informacyjnymi

Służy NuGet.Protocol do pracy z uwierzytelnionymi kanałami informacyjnymi.

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

NuGet.Packaging Zainstaluj pakiet w celu interakcji z plikami .nupkg i .nuspec ze strumienia:

dotnet add package NuGet.Packaging

Tworzenie pakietu

Utwórz pakiet, ustaw metadane i dodaj zależności przy użyciu polecenia NuGet.Packaging.

Ważne

Zdecydowanie zaleca się utworzenie pakietów NuGet przy użyciu oficjalnego narzędzia NuGet, a nie przy użyciu tego interfejsu API niskiego poziomu. Istnieje wiele cech istotnych dla dobrze sformułowanego pakietu, a najnowsza wersja narzędzi pomaga uwzględnić te najlepsze rozwiązania.

Aby uzyskać więcej informacji na temat tworzenia pakietów NuGet, zobacz omówienie przepływu pracy tworzenia pakietów i dokumentację oficjalnego narzędzia pakietów (na przykład przy użyciu interfejsu wiersza polecenia 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}");

Odczytywanie pakietu

Odczytywanie pakietu ze strumienia plików przy użyciu polecenia 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}");
}

Dokumentacja innej firmy

Przykłady i dokumentacja niektórych interfejsów API można znaleźć w następującej serii blogów Dave Glick, opublikowanej w 2016 r.:

Uwaga

Te wpisy w blogu zostały napisane wkrótce po wydaniu wersji 3.4.3 pakietów zestawu SDK klienta NuGet. Nowsze wersje pakietów mogą być niezgodne z informacjami w wpisach w blogu.

Martin Björkström wykonał kontynuację wpisu w blogu Dave'a Glicka, w którym wprowadza inne podejście do używania zestawu SDK klienta NuGet do instalowania pakietów NuGet: