ActionsToolkit.ToolCache 1.0.0

ActionsToolkit.ToolCache package

To install the ActionsToolkit.ToolCache NuGet package:

<PackageReference Include="ActionsToolkit.ToolCache" Version="[Version]" />

Or use the dotnet add package .NET CLI command:

dotnet add package ActionsToolkit.ToolCache

Get the IToolCacheService instance

ActionsToolkit.ToolCache is the .NET equivalent of the official @actions/tool-cache Node package. It exposes IToolCacheService for downloading, extracting, caching, and resolving tools on a self-hosted or hosted runner. Register the service with an IServiceCollection by calling AddGitHubActionsToolCache() and consume IToolCacheService via constructor dependency injection.

using Microsoft.Extensions.DependencyInjection;
using ActionsToolkit.ToolCache;
using ActionsToolkit.ToolCache.Extensions;

using var provider = new ServiceCollection()
    .AddGitHubActionsToolCache()
    .BuildServiceProvider();

var toolCache = provider.GetRequiredService<IToolCacheService>();

The extension transitively registers ActionsToolkit.HttpClient so the IHttpClient used for downloads is fully resilient (Polly-backed).

Usage

The runner sets two environment variables that this package consults:

Download

var nodePath = await toolCache.DownloadToolAsync(
    "https://nodejs.org/dist/v20.10.0/node-v20.10.0-linux-x64.tar.gz");

Extract

The .NET port uses SharpCompress for tar/tar.gz/tar.xz/tar.bz2/zstd/7z extraction (no native tar / 7z.exe shell-out is required). For zip the BCL System.IO.Compression is used.

var extracted = await toolCache.ExtractTarAsync(nodePath);
// or:
var extracted = await toolCache.ExtractZipAsync(zipPath);
var extracted = await toolCache.Extract7zAsync(sevenZipPath);

ExtractXarAsync throws PlatformNotSupportedException: SharpCompress does not ship xar support, so consumers should shell out to the native xar binary on macOS instead.

Cache

var cached = await toolCache.CacheDirAsync(extracted, "node", "20.10.0");
// or cache a single file (e.g. a downloaded GUID) under a friendly name:
var cached = await toolCache.CacheFileAsync(downloaded, "node.exe", "node", "20.10.0");

Find

var nodeDir = toolCache.Find("node", "20.x");
var allVersions = toolCache.FindAllVersions("node");

Versions manifest

var manifest = await toolCache.GetManifestFromRepoAsync(
    owner: "actions",
    repo: "node-versions",
    authToken: token,
    branch: "main");

var release = await toolCache.FindFromManifestAsync("20.x", stable: true, manifest);

Evaluate versions

var versions = new[] { "1.0.0", "1.2.3", "2.0.0", "3.0.1-beta" };
var match = toolCache.EvaluateVersions(versions, "1.x"); // "1.2.3"

Native AOT

The package is fully compatible with .NET Native AOT. JSON (de)serialization is driven entirely by source-generated JsonSerializerContexts — no reflection-based serializer overloads are called, no dynamic code is generated. A dedicated AOT smoke-test project (tests/ActionsToolkit.ToolCache.Aot.Tests) publishes a small consumer with <PublishAot>true</PublishAot> and exercises every public API to guard against IL2026/IL3050 regressions.

Attribution

This package is a .NET port of the official @actions/tool-cache Node.js package by GitHub, licensed under the MIT License.

Archive extraction is delegated to SharpCompress, licensed under the MIT License.

The npm-style semver subset is hand-rolled and modeled on node-semver, also under the MIT License.