EncySoftware.Helpers.Nuget 2.0.3

NuGetHelper

A .NET 8 library that provides a high-level API for working with NuGet feeds and packages — querying metadata, downloading, pushing, verifying integrity, and reading embedded instructions.

Installation

dotnet add package EncySoftware.Helpers.Nuget

Quick Start

using Helpers.Nuget;
using Helpers.Nuget.Model;
using NuGet.Versioning;

var helper = new NuGetHelper();

var storage = new StorageInfo("https://api.nuget.org/v3/index.json");

StorageInfo

StorageInfo describes a NuGet feed source passed to every operation.

API Overview

Metadata — query package info without downloading

// Get package metadata
var info = await helper.Metadata.GetPackageInfo(
    new[] { storage }, "MyPackage", new NuGetVersion("1.0.0"));

// List all available versions
var versions = await helper.Metadata.GetVersions(new[] { storage }, "MyPackage");

// Get direct NuGet dependencies
var deps = await helper.Metadata.GetDirectDependencies(
    new[] { storage }, "MyPackage", new NuGetVersion("1.0.0"));

// Search by term
await foreach (var pkg in helper.Metadata.Search(new[] { storage }, "logging"))
    Console.WriteLine(pkg.Identity);

Searching by tag lives in List — see below.

Actions — push, delete, download

// Push a package
await helper.Actions.Push(new[] { storage }, "MyPackage.1.0.0.nupkg");

// Delete a package
await helper.Actions.Delete(
    new List<StorageInfo> { storage }, "MyPackage", new NuGetVersion("1.0.0"));

// Download to local NuGet cache (returns path to the extracted folder)
var path = await helper.Actions.Download(
    new List<StorageInfo> { storage }, "MyPackage", new NuGetVersion("1.0.0"), force: false);

List — enumerate packages by tag

// Get all packages that have any of the specified tags
var packages = await helper.List.Get(new[] { storage }, new[] { "tool", "cli" });

The answer is a list of PackageIdentity — id plus the exact versions carrying the tag. Read whatever metadata you need for the ones you are going to show, through Metadata.GetAllVersionsMetadata or Metadata.GetPackageInfo; the search itself does not fetch descriptions.

How a source is asked depends on its StorageInfo.FeedType. A Standard feed is asked a Tags:"x" search and its answer is taken as given. A Nexus feed is asked through Sonatype's own component API (/service/rest/v1/search?nuget.tags=…), because a Nexus keeps tags as a component attribute and never puts them into its NuGet search index: a Tags:"x" query there returns nothing, and a free-text query matches only a tag word that also happens to occur in a package id or description — a marker tag such as ency-extension is invisible to it. A feed declared as Nexus that does not serve that API fails with an error naming the feed, rather than silently returning an empty catalogue.

Instructions — read embedded JSON instructions (requires download first)

// Get instruction JSON embedded in the package
var json = helper.Instructions.Get("MyPackage", new NuGetVersion("1.0.0"));

// Get all dependencies described in instructions (including transitive)
var allDeps = helper.Instructions.GetAllDependencies("MyPackage", new NuGetVersion("1.0.0"));

Protection — verify package integrity

// Verify package content against stored hashes or public key signature
bool valid = helper.Protection.VerifyPackageContent(
    "MyPackage", new NuGetVersion("1.0.0"), publicKey: myPublicKey);

Feed — check feed availability

// Simple availability check (certificate validation enabled)
bool available = await helper.Feed.IsFeedAvailableAsync("https://my.feed/v3/index.json");

// Full control — disable cert validation for self-signed certs
bool available = await helper.Feed.IsFeedAvailableAsync(
    new StorageInfo("https://internal.feed/v3/index.json") { ValidateServerCertificate = false });

Feeds behind a private certificate authority

A feed whose server certificate is issued by a CA that is not installed on the client machine can be trusted by handing that CA to the source, instead of turning validation off:

// corporateCa is an X509Certificate2 — load it from your own resources or from disk
var storage = new StorageInfo("https://internal.feed/v3/index.json")
{
    CustomRootCertificate = corporateCa
};

The CA is trusted in addition to the machine's root store, so public feeds keep working unchanged. Unlike ValidateServerCertificate = false, the server still has to prove it holds a certificate for the requested host issued by that CA — a certificate from any other issuer, or for any other host, is rejected. Revocation is not checked against the custom root, since a private CA's CRL/OCSP endpoints are usually unreachable from the client.

Feeds gated by a client certificate (mutual TLS)

A feed that only admits callers presenting a personal certificate can be given one directly, without declaring the source in NuGet.Config:

// personalCertificate is an X509Certificate2 — the caller owns loading it and any password
var storage = new StorageInfo("https://internal.feed/v3/index.json")
{
    ClientCertificate = personalCertificate
};

When set, the clientCertificates section of NuGet.Config is not consulted for that source; when left null, the certificate is looked up there by source URL as before. The same certificate is used by the availability probe and by every feed operation, so a feed that reports as available also downloads.

Such a feed refuses an unauthenticated caller with HTTP 401 or 403 — or, when it sits behind an nginx ssl_verify_client gate, with HTTP 400 and the gate's own message (No required SSL certificate was sent, or The SSL certificate error for a certificate that was presented but not accepted). All of these are reported as FeedAvailability.ClientCertificateRequired — distinct from Unreachable, so a caller can prompt for a certificate instead of reporting an outage:

var availability = await helper.Feed.IsFeedAvailableAsync(storage);
if (availability == FeedAvailability.ClientCertificateRequired)
{
    // ask the user for a certificate, then retry with storage.ClientCertificate set
}

Note that 401 and 403 are how any feed refuses a caller it does not accept, so this value means "the feed rejected who you are" — a token-authenticated feed (RequestHeadersProvider) reports it too when its token is missing or expired. A plain 400 without a gate message stays Unreachable, since on its own it says nothing about certificates.

Cache — manual cache management

// Put information into cache manually when needed
helper.Cache /* see ICache for available operations */;

PerformanceCounter

NuGetHelper.PerformanceCounter collects execution times for internal operations and can be used to monitor performance.

Logging

Pass an INuGetHelperLogger implementation to the constructor to receive diagnostic output:

var helper = new NuGetHelper(myLogger);